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}/agentPede 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 |