API — Conversas e Mensagens (Chat / WhatsApp)
Listar e atualizar conversas, ler o histórico de mensagens e enviar mensagens (texto e mídia) por conversa ou por telefone. O padrão recomendado para responder a webhooks é usar conversation_id.
API — Conversas e Mensagens
Acesso ao inbox de chat (WhatsApp): conversas, histórico e envio de mensagens. Base: /api/v1.

Endpoints
| Método | Path | Descrição |
|---|---|---|
| GET | /conversations | Listar conversas |
| GET | /conversations/{id} | Detalhes da conversa |
| PUT | /conversations/{id} | Atualizar (status, atribuição) |
| GET | /conversations/{id}/messages | Histórico de mensagens (cursor) |
| POST | /conversations/{id}/messages | Enviar mensagem nessa conversa |
| POST | /messages/send | Enviar por conversation_id OU por phone+channel_id |
GET /conversations — filtros
| Parâmetro | Tipo | Descrição |
|---|---|---|
| status | string | open, pending, resolved, bot |
| channel_id | integer | canal WhatsApp |
| assigned_to | integer | atendente (user_id) |
| contact_id | integer | contato |
| search | string | nome, número (remote_jid) ou prévia |
| is_group | boolean | somente grupos |
| sort_by | string | last_message_at, created_at, unread_count |
| sort_dir | string | asc | desc (padrão desc) |
| per_page | integer | padrão 50, máx 100 |
PUT /conversations/{id}
Campos opcionais: status (open|pending|resolved), assigned_user_id (integer ou null para remover), assigned_department_id (integer ou null). As mudanças são registradas no histórico da conversa com a nota "via API".
PUT /api/v1/conversations/123
{ "status": "resolved" }
GET /conversations/{id}/messages — paginação por cursor
| Parâmetro | Tipo | Descrição |
|---|---|---|
| limit | integer | padrão 50, máx 100 |
| before_id | integer | mensagens com id menor (mais antigas) |
| after_id | integer | mensagens com id maior (mais novas) |
Retorna as mensagens em ordem cronológica crescente e o campo has_more (true quando vieram exatamente limit registros — peça a próxima página com before_id = id da mensagem mais antiga retornada).
{
"data": [ { "id": 4990, "direction": "incoming", "type": "text", "content": "Olá", "status": "delivered", "created_at": "..." } ],
"has_more": true
}
POST /conversations/{id}/messages — enviar na conversa
| Campo | Tipo | Descrição |
|---|---|---|
| content | string | texto (máx 10000). Obrigatório se não houver mídia |
| type | string | text, image, document, video, audio |
| media_url | url | URL pública da mídia |
| media | file | upload direto (multipart/form-data) |
| filename | string | nome do arquivo (para media_url) |
É preciso content OU mídia (media/media_url), senão 422. Ao enviar, a conversa é auto-atribuída ao usuário do token (se estiver sem responsável) e o status vira open. Mídia do tipo audio é enviada como mensagem de voz.
POST /messages/send — por conversa ou por telefone
Forma flexível para automações. Duas modalidades:
- Por conversa (recomendado em webhooks): informe
conversation_id.phoneechannel_idtornam-se desnecessários — a conversa já conhece o canal e o destinatário. - Por telefone: informe
phone+channel_id. Se ainda não existir conversa para aquele número no canal, ela é criada automaticamente.
| Campo | Tipo | Regras |
|---|---|---|
| conversation_id | integer | opcional; se ausente, channel_id passa a ser obrigatório |
| phone | string | ex: 5511999887766 (obrigatório no fluxo por telefone) |
| channel_id | integer | required_without:conversation_id |
| content, type, media_url, media, filename | — | iguais ao endpoint acima |
// Respondendo a um webhook (modo recomendado):
POST /api/v1/messages/send
{ "conversation_id": 678, "content": "Olá! Recebemos sua mensagem." }
// Iniciando por telefone:
POST /api/v1/messages/send
{ "phone": "5511999887766", "channel_id": 1, "content": "Confirmando seu agendamento." }
Resposta 201 traz a mensagem criada e, no fluxo por telefone, também o conversation_id resultante.
Erros de envio
Falhas de entrega retornam 400 com mensagens como "WhatsApp channel is disconnected." (canal desconectado) ou a mensagem específica do provedor. Conversa/canal inexistentes ⇒ 404.
Formato da mensagem
{
"id": 5001,
"conversation_id": 678,
"direction": "outgoing",
"type": "text",
"content": "Olá!",
"media_url": null,
"media_mimetype": null,
"filename": null,
"status": "sent",
"remote_message_id": "wamid...",
"sender_user": { "id": 2, "name": "Atendente" },
"metadata": null,
"created_at": "2026-03-15T10:31:00-03:00"
}