Conversations and Messages API: sending a message and checking delivery status

The Conversations and Messages API lets you read, create, and reply to conversations on any connected channel (WhatsApp, Instagram, Messenger, Webchat, etc.) from your own backend or automation tool, without opening the Inbox.

Requirements

• A Bearer token with access to the workspace.
• An existing conversation_id, or use find-or-create to get one from a contact + channel pair.

Main endpoints

• GET /api/v1/conversations — lists conversations (with ?workspace_id= and status filters).
• POST /api/v1/conversations/find-or-create — gets or creates the conversation for a contact+channel.
• GET /api/v1/conversations/{conversation} — detail view.
• POST /api/v1/conversations/{conversation}/messages — sends a message.
• GET /api/v1/conversations/{conversation}/messages — lists messages.
• GET /api/v1/conversations/{conversation}/messages/{message} — checks a specific message's status.
• POST /api/v1/conversations/{conversation}/assign, /close, /reopen — operational flow.

Body to send a message

{
  "content": "Hi, how can I help you today?",
  "type": "text",
  "is_internal_note": false,
  "reply_to_message_id": null
}

For WhatsApp templates, use "type": "template" with template_id and template_params.

Message statuses

Every message carries a status field with one of: queued, sent, delivered, read, failed. Check it via a GET on the message, or subscribe to the message.sent, message.delivered, message.read, and message.failed outbound webhook events.

Example: send a text message

curl -X POST "https://app.omnifox.io/api/v1/conversations/101/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Your order has shipped."}'

Tips

• Use is_internal_note: true to leave context visible only to agents, without sending it to the customer.
• On WhatsApp, if more than 24h have passed since the customer's last message, you can only re-open the conversation with an approved template (type: template).

Troubleshooting

• status: failed: check the message detail — this usually means an unapproved template, an expired 24h window, or an invalid number.
• 404 on /messages: the conversation_id doesn't exist or belongs to a different workspace.
• Message sent but the customer doesn't see it: verify is_internal_note wasn't accidentally set to true.