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.

Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.

Endpoints

MétodoPathDescrição
GET/conversationsListar conversas
GET/conversations/{id}Detalhes da conversa
PUT/conversations/{id}Atualizar (status, atribuição)
GET/conversations/{id}/messagesHistórico de mensagens (cursor)
POST/conversations/{id}/messagesEnviar mensagem nessa conversa
POST/messages/sendEnviar por conversation_id OU por phone+channel_id

GET /conversations — filtros

ParâmetroTipoDescrição
statusstringopen, pending, resolved, bot
channel_idintegercanal WhatsApp
assigned_tointegeratendente (user_id)
contact_idintegercontato
searchstringnome, número (remote_jid) ou prévia
is_groupbooleansomente grupos
sort_bystringlast_message_at, created_at, unread_count
sort_dirstringasc | desc (padrão desc)
per_pageintegerpadrã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âmetroTipoDescrição
limitintegerpadrão 50, máx 100
before_idintegermensagens com id menor (mais antigas)
after_idintegermensagens 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

CampoTipoDescrição
contentstringtexto (máx 10000). Obrigatório se não houver mídia
typestringtext, image, document, video, audio
media_urlurlURL pública da mídia
mediafileupload direto (multipart/form-data)
filenamestringnome 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. phone e channel_id tornam-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.
CampoTipoRegras
conversation_idintegeropcional; se ausente, channel_id passa a ser obrigatório
phonestringex: 5511999887766 (obrigatório no fluxo por telefone)
channel_idintegerrequired_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"
}
api chat conversas mensagens whatsapp integração

Este artigo foi útil?

Artigos Relacionados