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.
Lifecycle states
| 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). |
Tracking lifecycle changes
There are two ways to track these status updates:
- Webhooks (Recommended): Subscribe to the
message.status_updateevent. 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.
Delivery idempotency
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(orwebhook-id) header. - For full details, see Message lifecycle and idempotency.