Conversas

Gerencie conversas com clientes em todos os canais de atendimento. Uma conversa representa uma thread de mensagens entre um contato e sua equipe.

Base URL

Todos os endpoints usam o prefixo /api/v1/accounts/{account_id}

GET/api/v1/accounts/{account_id}/conversations

Retorna uma lista paginada de conversas com filtros opcionais.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`assignee_type`(query)	`string`	Nao	Filtrar por tipo de atribuicao: me, unassigned, all, assigned
`status`(query)	`string`	Nao	Filtrar por status: open, resolved, pending, snoozed, all
`q`(query)	`string`	Nao	Buscar por texto nas mensagens
`inbox_id`(query)	`integer`	Nao	Filtrar por inbox
`team_id`(query)	`integer`	Nao	Filtrar por equipe
`labels`(query)	`array`	Nao	Filtrar por etiquetas
`page`(query)	`integer`	Nao	Numero da pagina para paginacao

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations?status=open&page=1" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de conversas com metadados

json

{
  "data": {
    "meta": {
      "mine_count": 5,
      "unassigned_count": 12,
      "all_count": 42
    },
    "payload": [
      {
        "id": 123,
        "inbox_id": 1,
        "status": "open",
        "messages": [...],
        "contact": { "id": 456, "name": "Joao Silva" },
        "assignee": { "id": 1, "name": "Agente 1" }
      }
    ]
  }
}

POST/api/v1/accounts/{account_id}/conversations

Cria uma nova conversa com um contato em um inbox especifico.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta

Body

Nome	Tipo	Obrigatorio	Descricao
`source_id`	`string`	Sim	ID da origem do contato (contact source)
`inbox_id`	`integer`	Sim	ID do inbox onde criar a conversa
`contact_id`	`integer`	Nao	ID do contato (alternativa a source_id)
`status`	`string`	Nao	Status inicial: open, pending
`assignee_id`	`integer`	Nao	ID do agente responsavel
`team_id`	`integer`	Nao	ID da equipe responsavel
`message`	`object`	Nao	Mensagem inicial: { content, content_type }

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "contact_source_id",
    "inbox_id": 1,
    "message": {
      "content": "Ola, como posso ajudar?"
    }
  }'

200Conversa criada

json

{
  "id": 124,
  "inbox_id": 1,
  "status": "open",
  "contact": { "id": 456, "name": "Joao Silva" },
  "created_at": "2026-02-15T10:30:00.000Z"
}

GET/api/v1/accounts/{account_id}/conversations/{conversation_id}

Retorna os detalhes completos de uma conversa especifica.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`conversation_id`(path)	`integer`	Sim	ID numerico da conversa

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations/123" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Detalhes da conversa

json

{
  "id": 123,
  "inbox_id": 1,
  "status": "open",
  "priority": "medium",
  "contact": { "id": 456, "name": "Joao Silva" },
  "assignee": { "id": 1, "name": "Agente 1" },
  "team": { "id": 2, "name": "Suporte" },
  "labels": ["vip", "urgente"],
  "additional_attributes": {},
  "created_at": "2026-02-15T10:30:00.000Z"
}

PATCH/api/v1/accounts/{account_id}/conversations/{conversation_id}

Atualiza atributos de uma conversa como status, atribuicao ou prioridade.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`conversation_id`(path)	`integer`	Sim	ID numerico da conversa

Body

Nome	Tipo	Obrigatorio	Descricao
`assignee_id`	`integer`	Nao	ID do agente responsavel
`team_id`	`integer`	Nao	ID da equipe
`status`	`string`	Nao	Status: open, resolved, pending
`priority`	`string`	Nao	Prioridade: none, low, medium, high, urgent

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/conversations/123" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_id": 5, "priority": "high" }'

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status

Alterna o status da conversa (abrir/resolver/pendente).

Body

Nome	Tipo	Obrigatorio	Descricao
`status`	`string`	Sim	Novo status: open, resolved, pending, snoozed

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/toggle_status" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_priority

Define a prioridade da conversa.

Body

Nome	Tipo	Obrigatorio	Descricao
`priority`	`string`	Sim	Prioridade: none, low, medium, high, urgent

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/toggle_priority" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent" }'

POST/api/v1/accounts/{account_id}/conversations/filter

Filtra conversas usando criterios avancados com operadores logicos.

Body

Nome	Tipo	Obrigatorio	Descricao
`payload`	`array`	Sim	Array de filtros com attribute_key, filter_operator, values e query_operator

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/filter" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [
      {
        "attribute_key": "status",
        "filter_operator": "equal_to",
        "values": ["open"],
        "query_operator": "AND"
      },
      {
        "attribute_key": "assignee_id",
        "filter_operator": "equal_to",
        "values": [1]
      }
    ]
  }'

GET/api/v1/accounts/{account_id}/conversations/meta

Retorna contadores de conversas agrupados por status e atribuicao.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`status`(query)	`string`	Nao	Filtrar por status
`q`(query)	`string`	Nao	Buscar por texto
`inbox_id`(query)	`integer`	Nao	Filtrar por inbox
`team_id`(query)	`integer`	Nao	Filtrar por equipe
`labels`(query)	`array`	Nao	Filtrar por etiquetas

200Contadores de conversas

json

{
  "meta": {
    "mine_count": 5,
    "unassigned_count": 12,
    "assigned_count": 8,
    "all_count": 25
  }
}

Etiquetas da Conversa

GET/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels

Lista as etiquetas associadas a uma conversa.

200Lista de etiquetas

json

{ "payload": ["vip", "urgente", "suporte-tecnico"] }

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels

Define as etiquetas de uma conversa (substitui todas as existentes).

Body

Nome	Tipo	Obrigatorio	Descricao
`labels`	`array`	Sim	Array de strings com as etiquetas

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/labels" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["vip", "alta-prioridade"] }'

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments

Atribui um agente a uma conversa.

Body

Nome	Tipo	Obrigatorio	Descricao
`assignee_id`	`integer`	Nao	ID do agente (null para remover atribuicao)
`team_id`	`integer`	Nao	ID da equipe

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/assignments" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_id": 5, "team_id": 2 }'