Message queue
Understand what happens after the API accepts a message and how to build reliable retry behavior.
Queue lifecycle
When `/api/messages/send` or `/api/otp/send` returns `queued`, the request has passed validation and has been stored for background delivery.
A queued response is not a delivery receipt. The worker still needs the sender to be connected, under limit, and able to reach WhatsApp.
How to integrate safely
Store the returned `message_id` beside your own order, ticket, login attempt, or notification record. Use that ID for support lookups and status reconciliation.
For critical flows, combine idempotency keys with polling or webhooks. Idempotency prevents duplicate sends when your application retries a request after a timeout.
/api/messages/{message_id}Poll message status after a queued send.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | API key with access to the sender used by the message. |
Idempotency keys
Send a stable `idempotency_key` for any operation your application might retry after a timeout. The key can be up to 160 characters.
If the same key is submitted again by the same API client, the API returns the existing message with `duplicate: true` instead of creating another send. The backend does not compare the new payload to the original payload, so do not reuse one key for different business events.
{
"message_id": "2b7a0bd5-1a0d-4e6c-85b1-a7f44f92dfb0",
"workspace_id": "f2aa1d49-9f4b-4f37-9918-d8d8f13fb530",
"status": "queued",
"duplicate": true
}Operator checks
If messages stay queued or fail repeatedly, check sender connection status, sender daily usage, workspace monthly quota, webhook delivery health, and worker health in the dashboard.
Do not immediately retry failed sends in a tight loop. Fix sender, input, quota, or recipient issues first, then retry through a controlled job or operator action.
Need help?
Use Book Integration Help if you want setup help for OTP or automated customer messaging.
Next steps
Quickstart
A practical path from empty workspace to a working server-side integration.
Authentication and access
HookMessage separates customer API keys, dashboard sessions, and internal platform access.
Workspaces
A workspace is the tenant boundary for every customer resource.
Senders and sessions
A sender is the WhatsApp number used to deliver messages for a workspace.