Webhooks3 min read · Updated 2026-06-01

message.failed

Receive webhook notifications when an outbound message fails to deliver.

The message.failed event fires when an outbound message cannot be delivered. Common causes include invalid phone numbers, expired session windows, or rejected templates.

Payload example

json

{
  "id": "evt_9b5c1d4e",
  "type": "message.failed",
  "createdAt": "2026-06-01T14:36:00Z",
  "data": {
    "messageId": "msg_jkl012",
    "conversationId": "conv_xyz789",
    "contactId": "cnt_def456",
    "channel": "whatsapp",
    "to": "+21612345678",
    "error": {
      "code": "session_expired",
      "message": "Cannot send session message outside the 24-hour window"
    }
  }
}

Common error codes

Code	Description
invalid_recipient	Phone number is invalid or not on WhatsApp
session_expired	Session message sent outside the 24-hour window
template_rejected	Template is not approved or parameters are invalid
rate_limited	Sending rate limit exceeded

HTTP response codes →

message.failed

Payload example

Common error codes

Need help with your integration?

message.failed

Payload example

Common error codes

Need help with your integration?