Operation
Delivery and retries
Understand queue acceptance, delivery receipts, and how to handle sends whose outcome is uncertain.
Read a message state#
Save the TurbineWhats.app message ID returned by a send. Use GET /messages/{id} with read permission to retrieve id, channel_id, kind, status, error, created_at, and updated_at under data.
curl 'https://turbinewhats.app/api/v1/messages/b4829d81-353f-4821-ae99-77adeab896ce' \
--header "Authorization: Bearer $TURBINEWHATS_TOKEN"Message states#
Delivery and read receipts depend on WhatsApp and the recipient’s settings. A message may stay sent without a later receipt. Some provider failure notifications arrive through webhooks without a corresponding normalized local state change. Polling the message state remains useful alongside event handling.
| State | Meaning |
|---|---|
| queued | Accepted and waiting for a worker. No delivery confirmation exists yet. |
| sending | The worker has begun dispatch to the gateway. |
| sent | The gateway acknowledged dispatch. Recipient delivery is not yet established. |
| delivered | An available WhatsApp receipt indicates delivery. |
| read | An available receipt indicates the recipient read the message. |
| rejected | Dispatch was refused before contacting the gateway, for example if access expired or the session disconnected. |
| uncertain | Dispatch started, but a conclusive outcome was not obtained. Check WhatsApp before creating a replacement. |
Choose a safe retry#
The worker does not automatically repeat ambiguous sends. This reduces duplicate delivery risk; it does not provide exactly-once delivery across WhatsApp.
- For a request timeout before receiving an API response, retry the same payload and the same idempotency key.
- For 429, wait for the relevant allowance window. Do not flood retries or switch keys to evade it.
- For session_not_ready, restore the connection and review the original message state before retrying.
- For uncertain, do not generate a replacement automatically. Check the actual WhatsApp conversation, then decide whether a deliberate new send is appropriate.