> ## Documentation Index
> Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Lifecycle

> Understand the statuses and timestamps that track every WhatsApp message on the Zapster API, from pending and scheduled to sent, delivered, read, or failed.

## Message statuses

Every message sent through Zapster goes through a lifecycle with well-defined statuses. The table below lists all the possible ones:

| Status      | Description                          | When it happens                            |
| ----------- | ------------------------------------ | ------------------------------------------ |
| `pending`   | Immediate message being processed    | When you send without `send_at`            |
| `scheduled` | Scheduled, waiting for its send time | When you send with `send_at`               |
| `sent`      | Successfully delivered to WhatsApp   | Send confirmed by the instance             |
| `failed`    | Send failed                          | After 3 unsuccessful attempts              |
| `canceled`  | Canceled by the user                 | When you call `DELETE /v1/wa/messages/:id` |

Once a message reaches `sent`, `failed`, or `canceled`, the status is final. It does not change again.

## Timestamps

Beyond the status, each message carries timestamps that show what happened and when. Not all of them are filled in on every message: it depends on the send type and on what happened afterward.

| Field          | Filled in when                      | Note                                           |
| -------------- | ----------------------------------- | ---------------------------------------------- |
| `created_at`   | The message is created              | Always present                                 |
| `send_at`      | Set by the user                     | Only exists on scheduled messages              |
| `sent_at`      | The message is sent successfully    | Filled in when WhatsApp accepts the send       |
| `delivered_at` | Delivery is confirmed on the device | When the message reaches the recipient's phone |
| `read_at`      | The recipient reads the message     | When the recipient opens the conversation      |
| `canceled_at`  | The message is canceled             | When the user calls `DELETE` before sending    |

## About delivery and read receipts

The `delivered_at` and `read_at` fields depend on factors outside Zapster's control:

* If the recipient turned off read receipts in their WhatsApp settings, `read_at` will never be filled in.
* If the recipient's phone has no internet, `delivered_at` may lag until they come back online.
* These fields do not change the message status. Once the status is `sent`, it stays `sent`. Delivery and read are extra pieces of information, recorded only in the timestamps.

In practice, you can use `delivered_at` and `read_at` to build delivery and read reports, but do not rely on them for critical flows. Not every recipient will generate these events.

## When a message fails

If a message has the status `failed`, the `errors` field carries a list with the details of what went wrong. The error structure varies a bit depending on the instance type.

For **official (WABA) instances**, `errors` includes Meta's error code and a direct link to their documentation:

```json theme={null}
{
  "errors": [
    {
      "code": 131047,
      "title": "Re-engagement message",
      "details": "More than 24 hours have passed since the recipient's last reply.",
      "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
    }
  ]
}
```

Some common errors on WABA instances:

* **131047**: The 24-hour window has expired. The recipient did not reply in the last 24h and you tried to send a non-template message.
* **132000**: Template not found. Check that the template name and language are correct.
* **131026**: The number is not on WhatsApp or is invalid.

For **unofficial (QR code) instances**, the most common errors are:

* The instance is offline (the phone lost connection or the session expired).
* The number is blocked or does not exist on WhatsApp.
* The WhatsApp send limit was reached.

In every case, the `errors` field carries enough information for you to understand what happened and decide whether it is worth trying again.