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