# message.status

HTML: https://www.app2email.com/docs/api/webhooks/message.status · Index: https://www.app2email.com/docs/api/llms.txt

A message sent from the number was sent, delivered, read, failed or deleted.

Group: Messages. Header `X-App2email-Event: message.status`. Inside the envelope `{id, type, created, number, test?, data}` ([envelope, headers, signature](https://www.app2email.com/docs/api/webhooks.md)). Every webhook of the number gets every number event: filter by `type`.

## data

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data.message_id` | string | yes |  |
| `data.to` | string | yes |  |
| `data.status` | string | yes | played: a voice message was played. clicked: a link in a Marketing Messages API message was clicked (no clicker identity).; one of: `sent`, `delivered`, `read`, `played`, `clicked`, `failed`, `deleted` |
| `data.timestamp` | string |  |  |
| `data.error` | object |  |  |
| `data.error.code` | integer |  | Meta's error code. |
| `data.error.message` | string |  |  |
| `data.error.title` | string |  |  |
| `data.error.details` | string |  |  |
| `data.error.href` | string |  |  |
| `data.error.error_code` | string |  | app2email's code for it: the same codes as API errors (/docs/api/errors). |
| `data.error.how_to_fix` | string |  |  |
| `data.error.is_retriable` | boolean |  |  |
| `data.error.retry_after_seconds` | integer |  |  |
| `data.sent_by` | string |  | api, dashboard, broadcast, email, autoreply ... |
| `data.broadcast_code` | string |  |  |
| `data.whatsapp_status` | string |  | Meta's status, unchanged. |
| `data.pricing` | object |  | What Meta charges for the message (on one of its statuses). |
| `data.pricing.billable` | boolean |  |  |
| `data.pricing.pricing_model` | string |  |  |
| `data.pricing.type` | string |  | regular, free_customer_service, free_entry_point ... |
| `data.pricing.category` | string |  |  |
| `data.callback_data` | string |  | The biz_opaque_callback_data given when sending. |
| `data.recipient_user_id` | string |  | The contact's business-scoped user id. |
| `data.recipient_identity_key_hash` | string |  | The contact's identity key hash, when the identity check is on (PUT /settings/identity-check). |
| `data.conversation` | object |  | Meta's conversation object, when it sends one.; any keys |
| `data.whatsapp` | object |  | Meta's object, unchanged.; any keys |

## Samples

### delivered

```json
{
  "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
  "type": "message.status",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "to": "61412345678",
    "status": "delivered",
    "timestamp": "2026-11-06T01:00:00.000Z",
    "sent_by": "api",
    "whatsapp_status": "delivered",
    "recipient_user_id": "AU.1234567890123456",
    "pricing": {
      "billable": true,
      "pricing_model": "PMP",
      "type": "regular",
      "category": "utility"
    },
    "callback_data": "order-1234"
  }
}
```

### played

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs010",
  "type": "message.status",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "to": "61412345678",
    "status": "played",
    "timestamp": "2026-11-06T01:00:00.000Z",
    "sent_by": "api",
    "whatsapp_status": "played"
  }
}
```

## Caused by

- [Send a WhatsApp message: template, or free-form reply](https://www.app2email.com/docs/api/messages/send-template-message.md): `POST /v1/{number}/messages`
- [Delete a contact record](https://www.app2email.com/docs/api/contacts/delete-contact.md): `DELETE /v1/{number}/contacts/{identity}`
- [Approve a held send: it is sent now](https://www.app2email.com/docs/api/approvals/approve-send.md): `POST /v1/{number}/approvals/{id}/approve`
- [Book an appointment for a customer at a free slot](https://www.app2email.com/docs/api/book-and-pay/create-booking.md): `POST /v1/{number}/bookings`
- [Cancel an appointment](https://www.app2email.com/docs/api/book-and-pay/cancel-booking.md): `POST /v1/{number}/bookings/{id}/cancel`

Send it to your URL: https://www.app2email.com/docs/api/webhooks/tester?type=message.status
