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.
- queued: accepted and waiting for a worker.
- sent: delivered to WhatsApp successfully.
- failed: delivery was attempted and did not succeed.
- duplicate: idempotency returned an existing message instead of creating a new one.
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.
- Recommended pattern: `order:{orderId}:confirmed` for one order confirmation.
- Recommended pattern: `login:{attemptId}:otp` for one OTP attempt.
- Retry after timeout: retry with the same key and store the returned `message_id`.
- Different payload: use a different key when message text, receiver, attachment, or business event changes.
- Different API client: a reused key owned by another client is rejected with `forbidden`.
{
"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.
Continue building
Next steps
Start here
A plain-language map of Free Sandbox, paid sender modes, credentials, and the first successful request.
Free Sandbox quickstart
The shortest beginner path from a verified account to a queued Free Sandbox OTP.
Glossary
Understand workspaces, keys, senders, receivers, queue states, webhooks, and idempotency.
Authentication and access
HookMessage separates customer API keys, dashboard sessions, and internal platform access.