> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/api-integration-guide/webhooks/delivery-status-callback.md).

# Delivery Status Callback

The **Delivery Status Callback** provides updates about the status of outbound WhatsApp messages sent through Taqnyat's API.

Each delivery report is returned inside the `statuses` array of the webhook payload.

### Callback Structure

A delivery report may contain the following fields:

| Field        | Type   | Description                                                                |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `status`     | String | Indicates whether the message status update represents success or failure. |
| `state`      | String | Current state of the message.                                              |
| `message_id` | String | ID of the message associated with the delivery report.                     |
| `details`    | String | Additional information about the status update.                            |
| `recipient`  | String | Recipient associated with the message.                                     |
| `timestamp`  | String | ISO-8601 date and time of the status update.                               |

### Example Payload

The following example shows the general structure of a delivery status callback:

```json
{
  "type": "whatsapp",
  "statuses": [
    {
      "status": "success",
      "state": "delivered",
      "message_id": "<MESSAGE_ID>",
      "details": "",
      "recipient": "9665XXXXXXXX",
      "timestamp": "2026-08-17T12:30:00Z"
    }
  ]
}
```

> The values shown above are illustrative. The structure and field names follow the current Taqnyat API reference.

### Message States

The `state` field indicates the current stage of the message:

| State           | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `queued`        | Message has been received and queued by the Taqnyat WhatsApp API.             |
| `dispatched`    | Message has been dispatched by Taqnyat to WhatsApp servers.                   |
| `sent`          | Message has been sent by WhatsApp to the end user.                            |
| `delivered`     | Message has been successfully delivered to the end user.                      |
| `read`          | Message has been read by the end user in WhatsApp.                            |
| `deleted`       | Message has been deleted or expired in the application.                       |
| `failed`        | Message delivery has failed.                                                  |
| `no_opt_in`     | Message was rejected because the recipient is not registered as opted in.     |
| `no_capability` | Message was rejected because the recipient does not have WhatsApp capability. |

### Tracking a Message

Use the `message_id` returned when sending a WhatsApp message to associate the callback with the original request.

For example:

```json
{
  "message_id": "<MESSAGE_ID>",
  "state": "read"
}
```

Your application can use this value to update the status of the corresponding message in your own system.

### Failed Messages

When the message cannot be delivered, the callback may contain:

```json
{
  "status": "failure",
  "state": "failed",
  "message_id": "<MESSAGE_ID>",
  "details": "<FAILURE_DETAILS>",
  "recipient": "9665XXXXXXXX",
  "timestamp": "2026-08-17T12:30:00Z"
}
```

The `details` field should be reviewed to understand the available information related to the failure.

### Expected Response

After receiving the callback, your server should respond with a successful HTTP status code:

```http
HTTP/1.1 200 OK
```

If Taqnyat does not receive a response in the `2xx` range, the callback may be retried up to three times.

### Recommended Handling

Your application should:

* Match callbacks to messages using `message_id`.
* Store the latest message state.
* Allow for multiple status updates for the same message.
* Treat webhook processing as idempotent because callbacks may be retried.
* Review the `details` field when a message fails.