message.failed

Se envía cuando: Un mensaje saliente no se pudo enviar.

Qué trae data: Un objeto message con status: "failed", failed_at y error (con code y message). Los códigos de error posibles están en Enviar mensajes.

Para qué sirve: Avisar a tu equipo, reintentar con otro mensaje o corregir el número del destinatario.

Ejemplo

El cuerpo que recibe tu servidor (datos ficticios):

{
  "id": "evt_01EXAMPLE00000000000000005",
  "type": "message.failed",
  "created_at": "2026-01-01T12:00:00.000000Z",
  "workspace_id": "ten_01EXAMPLE00000000000000000",
  "data": {
    "message": {
      "id": "msg_01EXAMPLE00000000000000000",
      "instance_id": "ins_01EXAMPLE00000000000000000",
      "direction": "outbound",
      "type": "text",
      "status": "failed",
      "to": "5255000000001",
      "from": null,
      "group_id": null,
      "text": "Your order shipped",
      "caption": null,
      "media": null,
      "error": {
        "code": "RECIPIENT_NOT_ON_WHATSAPP",
        "message": "The recipient number does not have WhatsApp."
      },
      "created_at": "2026-01-01T11:59:58+00:00",
      "queued_at": "2026-01-01T11:59:58+00:00",
      "sent_at": null,
      "delivered_at": null,
      "read_at": null,
      "failed_at": "2026-01-01T12:00:05+00:00",
      "received_at": null
    }
  }
}

Todos los eventos comparten el mismo sobre (id, type, created_at, workspace_id, data) y los mismos headers de firma. Cómo verificarla, qué responder y cómo se reintenta: Webhooks.