Status messages webhook reference

This reference describes trigger events and payload contents for WhatsApp Business Account status messages webhook.

Triggers

• Your message is sent to a WhatsApp user.
• Your message is delivered to a WhatsApp user's device.
• Your message is displayed (i.e. "read") in the WhatsApp client on a WhatsApp user's device.
• Your message is unable to be sent to a WhatsApp user.
• Your message is unable to be delivered to a WhatsApp user's device.
• Your message is sent to a WhatsApp user in a group chat.

Note that the triggers above also apply to a WhatsApp user who is part of a group chat.

A status is considered read only if it has been delivered. In some cases, like when a user receives a message while in the chat screen, the message is both delivered and read at the same time. In these cases, the "delivered" webhook is not sent because it's implied that the message was delivered since it was read. This behavior is due to internal optimization.

Syntax

{   "object": "whatsapp_business_account",   "entry": [     {       "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",       "changes": [         {           "value": {             "messaging_product": "whatsapp",             "metadata": {               "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",               "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"             },             "statuses": [               {                 "id": "<WHATSAPP_MESSAGE_ID>",                 "status": "<STATUS>",                 "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",                 "recipient_id": "<USER_PHONE_NUMBER_OR_GROUP_ID>",                 "recipient_type": "group", <!-- Only included if message sent to a group -->                 "recipient_participant_id": "<GROUP_PARTICIPANT_USER_PHONE_NUMBER>", <!-- Only included if message sent to a group -->                 "recipient_identity_key_hash": "<IDENTITY_KEY_HASH>", <!-- Only included if identity change check enabled -->                 "biz_opaque_callback_data": "<BUSINESS_OPAQUE_DATA>", <!-- Only included if message sent with biz_opaque_callback_data -->                  <!-- (1) Only included with sent status, and one of either delivered or read status                      (2) Omitted entirely for v24.0+ unless webhook is for a free entry point conversation -->                 "conversation": {                   "id": "<CONVERSATION_ID>",                   "expiration_timestamp": "<CONVERSATION_EXPIRATION_TIMESTAMP>",                   "origin": {                     "type": "<CONVERSATION_CATEGORY>"                   }                 },                                  <!-- only included with sent status, and one of either delivered or read status -->                 "pricing": {                   "billable": <IS_BILLABLE?>,                   "pricing_model": "<PRICING_MODEL>",                   "type": "<PRICING_TYPE>",                   "category": "<PRICING_CATEGORY>"                 },                                  <!-- only included if failure to send or deliver message -->                 "errors": [                   {                     "code": <ERROR_CODE>,                     "title": "<ERROR_TITLE>",                     "message": "<ERROR_MESSAGE>",                     "error_data": {                       "details": "<ERROR_DETAILS>"                     },                     "href": "<ERROR_CODES_URL>"                   }                 ]               }             ]           },           "field": "messages"         }       ]     }   ] }

Parameters

Examples

This example webhook describes a marketing message that has been successfully sent from our servers.

 {   "object": "whatsapp_business_account",   "entry": [     {       "id": "102290129340398",       "changes": [         {           "value": {             "messaging_product": "whatsapp",             "metadata": {               "display_phone_number": "15550783881",               "phone_number_id": "106540352242922"             },             "statuses": [               {                 "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",                 "status": "sent",                 "timestamp": "1750030073",                 "recipient_id": "16505551234",                 "conversation": {                   "id": "72b14d6bd5407799e66f64d1b338e567",                   "expiration_timestamp": "1750116480",                   "origin": {                     "type": "marketing"                   }                 },                 "pricing": {                   "billable": true,                   "pricing_model": "PMP",                   "type": "regular",                   "category": "marketing"                 }               }             ]           },           "field": "messages"         }       ]     }   ] } 

This example v24.0 webhook describes a marketing message that has been displayed in the WhatsApp client (i.e. "read"). Notice that in this case, the conversation object is omitted because it's a v24.0 webhook, and the pricing object is omitted because it happened to be displayed in an associated delivered status messages webhook (the object can only appear in one or the other).

 {   "object": "whatsapp_business_account",   "entry": [     {       "id": "102290129340398",       "changes": [         {           "value": {             "messaging_product": "whatsapp",             "metadata": {               "display_phone_number": "15550783881",               "phone_number_id": "106540352242922"             },             "statuses": [               {                 "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",                 "status": "sent",                 "timestamp": "1750030073",                 "recipient_id": "16505551234"               }             ]           },           "field": "messages"         }       ]     }   ] } 

This example describes a message that failed to be sent.

 {   "object": "whatsapp_business_account",   "entry": [     {       "id": "102290129340398",       "changes": [         {           "value": {             "messaging_product": "whatsapp",             "metadata": {               "display_phone_number": "15550783881",               "phone_number_id": "106540352242922"             },             "statuses": [               {                 "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",                 "status": "failed",                 "timestamp": "1751142888",                 "recipient_id": "16505551234",                 "errors": [                   {                     "code": 131049,                     "title": "This message was not delivered to maintain healthy ecosystem engagement.",                     "message": "This message was not delivered to maintain healthy ecosystem engagement.",                     "error_data": {                       "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."                     },                     "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"                   }                 ]               }             ]           },           "field": "messages"         }       ]     }   ] }