Failed

The Failed status allows you to know that the message could not be delivered to the recipient’s phone number. You can use this status to identify undelivered messages and take appropriate action, such as retrying or verifying the recipient’s contact information.

Prerequisites

An active WhatsApp plan on Kaleyra platform.
An active WhatsApp for Business API plan that includes:
1. A WhatsApp business number.
2. An associated profile with the business number.
3. A WhatsApp verified and approved profile.
4. A WABA ID onboarded on Kaleyra WhatsApp API V2.
You must have the callback registered in the WhatsApp channel for the phone numbers.

Sample Webhook

The following is the sample webhook.

{
    "meta_object": {
        "value": {
            "messaging_product": "whatsapp",
            "metadata": {
                "display_phone_number": "9180XXXXX689",
                "phone_number_id": "10460XXXXX58833"
            },
            "statuses": [
                {
                    "id": "wamid.HBgMOTE5NDA3MDXXXXXA2ODYxRgSMjQzNjA1NDFBMXXXXXTYODg3AA==",
                    "status": "failed",
                    "timestamp": "1722XXXXX5",
                    "recipient_id": "9194XXXXXXXX",
                    "errors": [
                        {
                            "code": 131XX6,
                            "title": "Message Undeliverable."
                        }
                    ]
                }
            ]
        },
        "field": "messages"
    },
    "extra_info": {
        "trace_id": "8f14e45f-eXXX-4c1a-9e77-1a5XXXXXXXXX",
        "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==",
        "waba_id": "12XXXXX34512345",
        "ref": "campaign_2025_summer_sale",
        "ref1": "order_ORD_456789",
        "ref2": "payment_pending",
        "enable_url_tracking_body": false,
        "enable_url_tracking_button": false
    },
    "status":"failed",
    "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA",
}