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.
Event fields
data.idstringWhatsApp message ID, starting with
msg_. The same ID the send returned.data.senderstringPhone number the message was sent from, in E.164 format.
data.recipientstringRecipient phone number, in E.164 format.
data.templateobject or nullThe template sent:
id,name, andlanguage.data.occurred_atstringISO 8601 time WhatsApp reported for this status.
data.failure_codestringmeta_followed by WhatsApp's error code, such asmeta_131026, ormeta_errorwhen WhatsApp gave no code.data.failure_reasonstring or nullWhatsApp's explanation of the failure, when it gave one.
The payload never includes message content or variable values. Retrieve the message 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.
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 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.