# 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.







```shell
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.

1. For a request timeout before receiving an API response, retry the same payload and the same idempotency key.
2. For 429, wait for the relevant allowance window. Do not flood retries or switch keys to evade it.
3. For session_not_ready, restore the connection and review the original message state before retrying.
4. For uncertain, do not generate a replacement automatically. Check the actual WhatsApp conversation, then decide whether a deliberate new send is appropriate.