# whatsapp.message.failed

> A WhatsApp message could not be sent or delivered.

## When it fires

WhatsApp refused the message or could not deliver it. This includes a send request that returned `422` with the code `whatsapp_message_rejected` or `whatsapp_provider_unavailable`: that message is stored as `failed` and this event fires for it too.

It fires once per message, only before the message was delivered: a failure reported after delivery doesn't change the message and doesn't fire this event.

## Example payload

Example identifiers are shown below.

```json
{
  "id": "00000000-0000-4000-8000-000000000001",
  "type": "whatsapp.message.failed",
  "schema_version": 1,
  "data": {
    "id": "msg_example",
    "sender": "+213555000111",
    "recipient": "+213555123456",
    "template": {
      "id": "wat_example",
      "name": "order_update",
      "language": "en_US"
    },
    "occurred_at": "2026-10-14T09:30:02.000Z",
    "failure_code": "meta_131026",
    "failure_reason": "Message undeliverable"
  },
  "created_at": "2026-10-14T09:30:02.412Z"
}
```

## Event fields

| Field | Type | Description |
| --- | --- | --- |
| `data.id` | string | WhatsApp message ID, starting with `msg_`. The same ID the send returned. |
| `data.sender` | string | Phone number the message was sent from, in E.164 format. |
| `data.recipient` | string | Recipient phone number, in E.164 format. |
| `data.template` | object or null | The template sent: `id`, `name`, and `language`. |
| `data.occurred_at` | string | ISO 8601 time WhatsApp reported for this status. |
| `data.failure_code` | string | `meta_` followed by WhatsApp's error code, such as `meta_131026`, or `meta_error` when WhatsApp gave no code. |
| `data.failure_reason` | string or null | WhatsApp's explanation of the failure, when it gave one. |

The payload never includes message content or variable values. [Retrieve the message](/docs/api/messaging/retrieve) with `data.id` for its content, cost, and all its timestamps.

## Handle this event

Read `failure_code` and `failure_reason` to decide what to do. Some failures are permanent for the recipient, such as `meta_131026` (the number may not use WhatsApp) or `meta_131050` (the recipient stopped marketing messages); others are temporary. See [WhatsApp failure codes](/docs/whatsapp/best-practices#whatsapp-failure-codes).

To send again after fixing the cause, use a new idempotency key: a retry with the original key returns the failed message without sending.

[Verify the signature](/docs/webhooks/verify-webhooks-requests) before reading the payload. Deduplicate by the envelope `id`, not the message ID: one message has several events. Events can arrive out of order; compare `data.occurred_at`, or retrieve the message, before moving a status backwards.

---

Source: https://connect.nxiom.com/docs/webhooks/whatsapp/failed