Conversas e mensagens

Leia conversas do inbox multi-canal, envie mensagem, atribua, resolva, pause o agente de IA e peça para ele começar a atender.

Leia conversas do inbox multi-canal, envie mensagem, atribua, resolva, pause o agente de IA e peça para ele começar a atender.

{
  "id": "e5f7a9c1-3b4d-4e6f-8a0b-1c3d5e7f9a2b",
  "channel_id": "4a6b8c2d-1e3f-4a5b-8c7d-9e1f3a5b7c9d",
  "contact_id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
  "external_thread_id": "+5511987650001",
  "status": "open",
  "assignee_id": "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57",
  "handled_by": "user",
  "display_name": "João Silva",
  "last_message_at": "2026-08-01T14:30:00.000Z",
  "last_inbound_at": "2026-08-01T14:28:00.000Z",
  "unread_count": 0,
  "agent_status": "idle",
  "agent_paused_at": null,
  "deal_id": null,
  "is_group": false,
  "created_at": "2026-07-20T09:00:00.000Z",
  "updated_at": "2026-08-01T14:30:00.000Z"
}
Método Escopo Descrição
GET/api/conversations conversations:read Lista. Filtros: ?status=, ?channel_id=, ?assignee_id=, ?contact_id=
GET/api/conversations/{id} conversations:read Uma conversa
GET/api/conversations/{id}/messages conversations:read Mensagens (paginado)
POST/api/conversations/{id}/messages conversations:write Envia (201)
PATCH/api/conversations/{id} conversations:write Reatribuir, mudar status, pausar/retomar o agente
POST/api/conversations/{id}/agent conversations:write Pede para o agente de IA começar a atender a conversa — ver abaixo

O filtro ?status= da listagem aceita open, pending e resolved. Já o PATCH só aceita open e resolved — mandar pending devolve 400. Se o responsável pela chave estiver restrito a alguns canais, a API enxerga só esses. Com "Só o dele" em Conversas, a chave enxerga só as conversas atribuídas ao responsável pela chave — as do balcão (sem responsável) também ficam de fora — e as outras respondem 404, inclusive para mandar mensagem.

A listagem segue a ordem padrão (§6): conversas criadas mais recentemente primeiro. As mensagens de GET/api/conversations/{id}/messages também vêm da mais nova para a mais antiga:

{
  "id": "…",
  "conversation_id": "e5f7a9c1-…",
  "direction": "outbound",
  "sender_kind": "user",
  "sender_user_id": "1b7c9d2e-…",
  "body": "Vou te mandar a proposta em instantes.",
  "media_url": null,
  "media_type": null,
  "attachments": [],
  "reply_to_message_id": null,
  "status": "delivered",
  "external_id": "…",
  "failure_reason": null,
  "sent_at": "2026-08-01T14:30:01.000Z",
  "created_at": "2026-08-01T14:30:00.000Z"
}

Enviar mensagem

Três formatos, mutuamente exclusivos — exceto text + media, que podem vir juntos (legenda de anexo):

{ "text": "Vou te mandar a proposta em instantes." }
{ "media": [ { "url": "https://…/proposta.pdf", "mimeType": "application/pdf", "filename": "proposta.pdf" } ] }
{ "template": { "name": "reengajamento_padrao", "language": "pt_BR", "params": { "1": "Maria" } } }
Campo Regras
text até 4096 caracteres
media até 10 itens; cada um com url (http/https, até 2048), mimeType e filename opcional
template name e language obrigatórios; params opcional

⛔ Idempotency-Key é obrigatória aqui. Sem ela, 400.

A resposta 201 vem com status: "sending" — o envio acontece de forma assíncrona. O evento message.sent chega depois por webhook, e o status final (entregue, lida ou falhou) chega em message.updated. Não existe evento message.failed — a falha chega em message.updated.

?dry_run=true confere o corpo e se a chave enxerga a conversa, e nunca manda nada — por isso ele não antecipa a janela de 24h nem o estado do canal (ver §26.1).

Erro Código
Sem Idempotency-Key 400
Conversa inexistente, de um canal que esta chave não enxerga, ou de outro responsável ("Só o dele") 404
Texto puro fora da janela de 24h do WhatsApp oficial 409 — "Fora da janela de 24h. Use um template pra iniciar conversa."
Canal não suporta o que foi pedido 400

Reatribuir e resolver:

{ "assignee_id": "1b7c9d2e-…", "status": "resolved" }
Campo Regras
assignee_id uuid de uma pessoa ativa da equipe (§18), ou null para devolver a conversa ao balcão
status open ou resolved
agent_status paused_handoff (pausa o agente de IA, equivale a "Assumir" na tela) ou idle (retoma)

Resolver dispara conversation.resolved; atribuir a alguém dispara conversation.assigned. Aceita ?dry_run=true.

Erro Código
assignee_id que não é pessoa ativa desta conta 400
Conversa de outro responsável, com "Só o dele" em Conversas 404
A conversa mudou no meio da pausa ou da retomada do agente (outra pessoa ou o próprio agente mexeu nela) 409 — leia a conversa de novo e repita se ainda fizer sentido

Acionar o agente de IA

POST/api/conversations/{id}/agent

Pede para o agente de IA começar a atender aquela conversa — por exemplo, quando o seu sistema sabe que um lead acabou de chegar e quer que o atendimento automático assuma. Corpo vazio (ou {}); qualquer campo é recusado com 400.

⛔ Só funciona se algum agente da conta estiver com "Acionado por Requisição API" ligado, em Automações → Agentes → Quando atua. Ligar essa opção é o que autoriza a chamada; sem nenhum agente com ela ligada, a resposta é 409 e nada acontece.

{ "data": { "conversation_id": "e5f7a9c1-…", "agent_started": true } }

Se a conversa já tem um agente atendendo, ou o agente está pausado nela (alguém assumiu), nada muda e a resposta é 200 com agent_started: false e um reason explicando. Para tirar a pausa, use o PATCH com agent_status: "idle".

?dry_run=true faz todas as conferências (conversa visível, opção ligada) sem iniciar nada e responde { "conversation_id": "…", "agent_would_start": true }.

Erro Código
Conversa inexistente, de um canal que a chave não enxerga ou de outro responsável ("Só o dele") 404
Nenhum agente com "Acionado por Requisição API" ligado 409