---
title: "Message lifecycle"
description: "Learn how messages transition through queued, sent, delivered, and read states, and how to use idempotency."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.wazapin.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Message lifecycle

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

## Message lifecycle visualization

import MessageFlowDiagram from "@/components/react/MessageFlowDiagram";

The diagram above shows the typical lifecycle of a WhatsApp message — from send to read receipt.

## 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:
1. **Webhooks (Recommended):** Subscribe to the `message.status_update` event. Wazapin will post status updates to your server in real time.
2. **GET Polling:** Call the [GET /v1/messages/\{messageID\}](/api/reference-get-message) 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` (or `webhook-id`) header.
- For full details, see [Message lifecycle and idempotency](/api/message-lifecycle-idempotency).

## Related links
- [Set up webhooks](/receive-messages/overview)
- [GET /v1/messages/\{messageID\}](/api/reference-get-message)
- [Message lifecycle and idempotency reference](/api/message-lifecycle-idempotency)

Source: https://docs.wazapin.id/whatsapp-basics/message-lifecycle/index.mdx