Message lifecycle

Learn how messages transition through queued, sent, delivered, and read states, and how to use idempotency.

Every WhatsApp message sent through Wazapin goes through a series of status changes as it travels from your application to the recipient’s device.

When this matters

Tracking the message lifecycle is important when:

Confirming that critical notifications (like OTPs) were delivered to the user’s device.
Monitoring read rates for marketing or customer support chats.
Troubleshooting slow deliveries or message failures.
Handling duplicate webhook deliveries.

Status	Meaning
`queued`	Message accepted by Wazapin and placed in the outbox queue.
`sent`	Wazapin successfully dispatched the message to the WhatsApp/Meta network.
`delivered`	The message arrived at the recipient’s phone (double checkmarks in WhatsApp).
`read`	The recipient opened the message (blue double checkmarks in WhatsApp).
`failed`	The message could not be sent (e.g., invalid phone number, session closed).

There are two ways to track these status updates:

Webhooks (Recommended): Subscribe to the message.status_update event. Wazapin will post status updates to your server in real time.
GET Polling: Call the GET /v1/messages/{messageID} endpoint to retrieve the current state of a message.

Webhook delivery is guaranteed using a retry mechanism, which can occasionally result in duplicate events. To prevent duplicate processing:

Deduplicate incoming webhook events by checking the svix-id (or webhook-id) header.
For full details, see Message lifecycle and idempotency.