Conversations and Messages API: sending a message and checking delivery status
How to send messages via API to an Omnifox conversation and track their delivery status.
Watch this step in the video · Conversations and messages via API
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 usefind-or-createto 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: trueto 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: theconversation_iddoesn't exist or belongs to a different workspace. - Message sent but the customer doesn't see it: verify
is_internal_notewasn't accidentally set totrue.
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.