Test
Create an Agent
The WhatsApp Status Update Webhook Payload V2 allows you to receive real-time updates when the status of a message changes. Instead of checking manually whether a message was sent, delivered, read, or failed, WhatsApp automatically sends these updates to your webhook. This helps you track messages easily and keep your system up to date.
Sample Webhook
The following is the sample webhook.
- SENT
{
"meta_object": {
"field": "messages",
"value": {
"contacts": [
{
"user_id": "IN.33676092XXXXXXX",
"wa_id": "91940XXXXXX"
}
],
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "911XXXXXXXXX",
"phone_number_id": "649XXXXXXXXXXXX"
},
"statuses": [
{
"conversation": {
"expiration_timestamp": "1785488327",
"id": "713f27e00bad496XXXXXX4800353785c",
"origin": {
"type": "service"
}
},
"id": "wamid.HBgMOTE5NDA3MDA2ODYyFQIAERgSMXXXX0VGMTAzRjkzMzXXXXcyMA==",
"pricing": {
"billable": false,
"category": "service",
"pricing_model": "PMP",
"type": "free_customer_service"
},
"recipient_id": "91940XXXXXXX",
"recipient_user_id": "IN.3367609XXXXXXXX",
"status": "sent",
"timestamp": "1785488327"
}
]
}
},
"extra_info": {
"message_id": "45f0e60c-d0a7-459f-868a-40979160a98d",
"ref": "customer1",
"ref1": "marketing",
"ref2": "dictionary",
"trace_id": "4ff5f56d-18b5-4d76-9fe2-6XXXXXXb86da",
"waba_id": "660XXXXXXXXXX21"
},
"status": "sent",
"message_id": "45f0e60c-d0a7-459f-868a-4097XXXX916d"
}- Delivered
{ "meta_object": { "field": "messages", "value": { "contacts": [ { "user_id": "IN.336760XXXXXXXXX", "wa_id": "919407XXXXXX" } ], "messaging_product": "whatsapp", "metadata": { "display_phone_number": "91XXXXXXXXXX", "phone_number_id": "64XXXXX96988820" }, "statuses": [ { "conversation": { "id": "713f27e00bad4964XXXXX8003d53785c", "origin": { "type": "service" } }, "id": "wamid.HBgMOTE5NDA3MDA2ODYyFQIAERgSMXXXXX0VGQjJGMkzMzcyMjUwAA==", "pricing": { "billable": false, "category": "service", "pricing_model": "PMP", "type": "free_customer_service" }, "recipient_id": "919407XXXXXX", "recipient_user_id": "IN.336760XXXXXXXXX", "status": "delivered", "timestamp": "1785488328" } ] } }, "extra_info": { "message_id": "45f0e60c-d0a7-459f-868a-40979160a98d", "ref": "customer1", "ref1": "marketing", "ref2": "dictionary", "trace_id": "c447eb21-6ff1-4f79-a061-ee0XXXXX4140", "waba_id": "6602XXXXXXXXXX6" }, "status": "delivered", "message_id": "45f0e60c-d0a7-459f-868a-409XXXXX798d" } - Read
{ "meta_object": { "field": "messages", "value": { "contacts": [ { "user_id": "IN.3367609XXXXXXXXX", "wa_id": "919407XXXXXX" } ], "messaging_product": "whatsapp", "metadata": { "display_phone_number": "91XXXXXXXXXX", "phone_number_id": "649XXXXX6988820" }, "statuses": [ { "conversation": { "id": "713f27e00bad49648003cf85cd53785c", "origin": { "type": "service" } }, "id": "wamid.HBgMOTE5NDA3MDA2ODYyFQIAERgSXXXXXM0VGQjJGMTAzRjkzMUwAA==", "pricing": { "billable": false, "category": "service", "pricing_model": "PMP", "type": "free_customer_service" }, "recipient_id": "919407XXXXXX", "recipient_user_id": "IN.3367609XXXXXXXXX", "status": "read", "timestamp": "1785489059" } ] } }, "extra_info": { "message_id": "45f0e60c-d0a7-459f-868a-40XXXXX9791d", "ref": "customer1", "ref1": "marketing", "ref2": "dictionary", "trace_id": "eac6391c-2898-45db-9792-8XXXXX69a14b", "waba_id": "660XXXXXXXX2176" }, "status": "read", "message_id": "45f0e60c-d0a7-459f-868a-40XXXXX9798d" } - Failed
{ "meta_object": { "field": "messages", "value": { "contacts": [ { "user_id": "IN.37682698XXXXXXXX", "wa_id": "919407XXXXXX" } ], "messaging_product": "whatsapp", "metadata": { "display_phone_number": "91XXXXXXXXXX", "phone_number_id": "649XXXX64888820" }, "statuses": [ { "errors": [ { "code": 131047, "error_data": { "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number." }, "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/", "message": "Re-engagement message", "title": "Re-engagement message" } ], "id": "wamid.HBgMOTE3MDg5MzkxMzg3FQIAERgSQkZFXXX5RTc2RDBCNThDRTIyAA==", "recipient_id": "919407XXXXXX", "recipient_user_id": "IN.37682698XXXXXXXX", "status": "failed", "timestamp": "1785489389" } ] } }, "extra_info": { "message_id": "14fbc119-7146-44f4-8fa6-c5XXXXX27607", "ref": "customer1", "ref1": "marketing", "ref2": "dictionary", "trace_id": "d993ca88-1b1f-40bf-9aa2-b7XXXXXd3625", "waba_id": "6602XXXXXXXX172" }, "status": "failed", "message_id": "14fbc119-7146-44f4-8fa6-c52XXXX7e227" } - Not Sent - Number Opted Out
{ "code":"WAV2400", "status": "not sent", "reason": "message delivery failed as the number belongs to the blocklist", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==", "extra_info": { "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "waba_id": "12XXXXX34512345", "ref": "campaign_2025_summer_sale", "ref1": "Trasaction_TX_1234", "ref2": "payment_pending" } } - Not Sent - Daily Limit Reached
{ "code": "WAV2101", "status": "not sent", "reason": "Account daily limit reached", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==", "extra_info": { "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "waba_id": "12XXXXX34512345", "ref": "campaign_2025_summer_sale", "ref1": "order_ORD_456789", "ref2": "payment_pending" } } - Not Sent - To Number or Type Missing
{ "code": "WAV2400", "status": "not sent", "reason": "to number or type is missing in payload", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==", "extra_info": { "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "waba_id": "12XXXXX34512345", "ref": "campaign_2025_summer_sale", "ref1": "order_ORD_456789", "ref2": "payment_pending" } } - Not Sent - Template details Not found
{ "code":"WAV2400", "status": "not sent", "reason": "Template not found in our database. Try re-creating it via Kaleyra APIs/UI", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==", "extra_info": { "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "waba_id": "12XXXXX34512345", "ref": "campaign_2025_summer_sale", "ref1": "order_ORD_456789", "ref2": "payment_pending" } } - Not Sent - Country traffic blocked
{ "code": "WAV2102", "status": "not sent", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==", "reason": "Message delivery failed as traffic to the country is blocked", "extra_info": { "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "ref": "campaign_2025_summer_sale", "ref1": "order_ORD_456789", "ref2": "payment_pending", "waba_id": "12XXXXX34512345" } } - Not Sent - Missing slug value for URL tracking
{ "code": "WAV2400", "status": "not sent", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ", "reason": "To enable URL tracking, pass slug/{kadvanced} in dynamic button text", "extra_info": { "enable_url_tracking_body": true, "enable_url_tracking_button": true, "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "ref": "campaign_2025_summer_sale", "ref1": "order_ORD_456789", "ref2": "payment_pending", "waba_id": "12XXXXX34512345" } } - Submit - Success (for typing indicator and read receipts)
{ "status": "submitted", "message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ", "success": "1", "extra_info": { "message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA", "waba_id": "12XXXXX34512345", "ref": "campaign_2025_summer_sale", "ref1": "order_ORD_4XXX89", "ref2": "payment_confirmed" } } - Submit - Success
{
"message_id": "45f0e60c-d0a7-459f-868a-40979160a98d",
"meta_message_id": "wamid.HBgMOTE5NDA3MDA2ODYyFQIAERgSM0VGQjJGMTAzRjkzMzcyMjUwAA==",
"status": "submitted",
"extra_info": {
"message_id": "45f0e60c-d0a7-459f-868a-40979160a98d",
"ref": "customer1",
"ref1": "marketing",
"ref2": "dictionary",
"waba_id": "66021XXXX797166"
}
}- Submit - Failure
{
"status": "failed",
"message_id": "wamid.XXXXXHE5NXXXXXXXXXXDAQ==",
"error": {
"message": "Service temporarily unavailable",
"type": "<error_type>",
"code": <code>,
"fbtrace_id": "Service temporarily unavailable",
"error_data": {
"details": "The WhatsApp messaging service is experiencing temporary issues",
"messaging_product": "whatsapp"
}
},
"extra_info": {
"message_id": "wamid.HBgMOTE5NDAXXXXXX3MDFQIAERgSMEYxMEM1QjQ3QjXXXXXXQ2N0YA",
"waba_id": "12XXXXX34512345",
"ref": "campaign_2025_summer_sale",
"ref1": "order_ORD_456789",
"ref2": "payment_pending",
}
}Updated 19 days ago
Did this page help you?