API de Conversas e Mensagens: enviar uma mensagem e consultar status

A API de Conversas e Mensagens permite ler, criar e responder conversas de qualquer canal conectado (WhatsApp, Instagram, Messenger, Webchat, etc.) a partir do seu próprio backend ou ferramenta de automação, sem abrir o Inbox.

Requisitos

• Token Bearer com acesso ao workspace.
• Um conversation_id existente, ou use find-or-create para obtê-lo a partir de um contato + canal.

Endpoints principais

• GET /api/v1/conversations — lista conversas (com ?workspace_id= e filtros de status).
• POST /api/v1/conversations/find-or-create — obtém ou cria a conversa para um contato+canal.
• GET /api/v1/conversations/{conversation} — detalhe.
• POST /api/v1/conversations/{conversation}/messages — envia uma mensagem.
• GET /api/v1/conversations/{conversation}/messages — lista as mensagens.
• GET /api/v1/conversations/{conversation}/messages/{message} — consulta o status de uma mensagem específica.
• POST /api/v1/conversations/{conversation}/assign, /close, /reopen — fluxo operacional.

Corpo para enviar uma mensagem

{
  "content": "Olá, como posso ajudar?",
  "type": "text",
  "is_internal_note": false,
  "reply_to_message_id": null
}

Para modelos (templates) do WhatsApp, use "type": "template" com template_id e template_params.

Status de uma mensagem

Cada mensagem traz um campo status com um destes valores: queued, sent, delivered, read, failed. Consulte via GET na mensagem, ou assine os eventos message.sent, message.delivered, message.read e message.failed pelos Webhooks de saída.

Exemplo: enviar uma mensagem de texto

curl -X POST "https://app.omnifox.io/api/v1/conversations/101/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Seu pedido já foi despachado."}'

Dicas

• Use is_internal_note: true para deixar contexto visível apenas para agentes, sem enviar ao cliente.
• No WhatsApp, se passaram mais de 24h desde a última mensagem do cliente, só é possível reabrir a conversa com um modelo aprovado (type: template).

Solução de problemas

• status: failed: veja o detalhe da mensagem; geralmente indica modelo não aprovado, janela de 24h vencida ou número inválido.
• 404 em /messages: o conversation_id não existe ou pertence a outro workspace.
• Mensagem enviada mas o cliente não vê: confirme que is_internal_note não ficou true por engano.