# message.failed

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

A message sent from the number failed (the same data as message.status).

Group: Messages. Header `X-App2email-Event: message.failed`. 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

### failed

```json
{
  "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
  "type": "message.failed",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "to": "61412345678",
    "status": "failed",
    "timestamp": "2026-11-06T01:00:00.000Z",
    "error": {
      "code": 131026,
      "message": "Message Undeliverable.",
      "title": "Message undeliverable",
      "details": "Message Undeliverable.",
      "error_code": "recipient_unreachable",
      "how_to_fix": "WhatsApp could not deliver to this number. Check it is a WhatsApp number written with its country code (digits only, eg 61412345678), and that the person uses an up to date WhatsApp.",
      "is_retriable": false
    },
    "sent_by": "api",
    "whatsapp_status": "failed"
  }
}
```

### marketing limit

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs011",
  "type": "message.failed",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "to": "61412345678",
    "status": "failed",
    "timestamp": "2026-11-06T01:00:00.000Z",
    "sent_by": "broadcast",
    "whatsapp_status": "failed",
    "error": {
      "code": 131049,
      "message": "This message was not delivered to maintain healthy ecosystem engagement.",
      "title": "This message was not delivered to maintain healthy ecosystem engagement.",
      "error_code": "marketing_per_user_limit",
      "how_to_fix": "WhatsApp held this marketing message back: the person has had many marketing messages lately. Do not send it again within 24 hours, because retrying sooner keeps the block longer.",
      "is_retriable": false,
      "retry_after_seconds": 86400
    }
  }
}
```

## 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.failed
