# Status messages webhook reference | Developer Documentation

<div id="bkmrk-status-messages-webh">## Status messages webhook reference

<div><span>Updated: Nov 20, 2025</span></div><div>This reference describes trigger events and payload contents for WhatsApp Business Account status **messages** webhook.</div><div id="bkmrk-triggers"><div id="bkmrk-triggers-1"><div>### Triggers

</div></div></div><span>Your message is sent to a WhatsApp user.</span><span>Your message is delivered to a WhatsApp user’s device.</span><span>Your message is displayed (i.e. “read”) in the WhatsApp client on a WhatsApp user’s device.</span><span>Your message is unable to be sent to a WhatsApp user.</span><span>Your message is unable to be delivered to a WhatsApp user’s device.</span><span>Your message is sent to a WhatsApp user in a group chat.</span><span>Your voice message is played by the WhatsApp user’s device.</span><div>Note that the triggers above also apply to a WhatsApp user who is part of a group chat.</div><div>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.</div><div id="bkmrk-parameters"><div id="bkmrk-parameters-1"><div>### Parameters

</div></div></div><div><table><thead><tr><th><span>Placeholder </span></th><th><span>Description </span></th><th><span>Example value </span></th></tr></thead><tbody><tr><td><div><div>`<BUSINESS_DISPLAY_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>Business display phone number.</div></div></td><td><div><div>`15550783881`</div></div></td></tr><tr><td><div><div>`<BUSINESS_OPAQUE_DATA>`</div><div>*String*</div></div></td><td><div><div>String assigned by the business to the `biz_opaque_callback_data` property in the send message request.</div><div>Only included if the business set a `biz_opaque_callback_data` value when [sending](/books/meta-whatsapp/page/sending-messages-developer-documentation) the message.</div></div></td><td><div><div>`1744434060`</div></div></td></tr><tr><td><div><div>`<BUSINESS_PHONE_NUMBER_ID>`</div><div>*String*</div></div></td><td><div><div>Business phone number ID.</div></div></td><td><div><div>`106540352242922`</div></div></td></tr><tr><td><div><div>`<CONVERSATION_CATEGORY>`</div><div>*String*</div></div></td><td><div><div>[Conversation category](/books/meta-whatsapp/page/pricing-on-the-whatsapp-business-platform-developer-documentation). Values can be:</div><div>`authentication` — Indicates an authentication conversation.</div><div>`authentication_international` — Indicates an [authentication-international](/books/meta-whatsapp/page/authentication-international-rates-developer-documentation) conversation.</div><div>`marketing` — Indicates a marketing conversation.</div><div>`marketing_lite` — Indicates a [Marketing Messages API for WhatsApp](/books/meta-whatsapp/page/marketing-messages-api-for-whatsapp-developer-documentation) conversation.</div><div>`referral_conversion` — Indicates a free entry point conversation.</div><div>`service` — Indicates a service conversation.</div><div>`utility` — Indicates a utility conversation.</div></div></td><td><div><div>`service`</div></div></td></tr><tr><td><div><div>`<CONVERSATION_EXPIRATION_TIMESTAMP>`</div><div>*String*</div></div></td><td><div><div>Unix timestamp indicating when the conversation will expire.</div><div>The expiration_timestamp property is only included for `sent` status.</div></div></td><td><div><div>`1744434060`</div></div></td></tr><tr><td><div><div>`<CONVERSATION_ID>`</div><div>*String*</div></div></td><td><div><div>Version 24.0 and higher:</div><div>The `conversation` object will be omitted entirely, unless the webhook is for a message sent within an open free entry point window, in which case the value will be unique per window.</div><div>Version 23.0 and lower:</div><div>Value will now be set to a unique ID per-message, unless the webhook is for a message sent with an open free entry point window, in which case the value will be unique per window.</div></div></td><td><div><div>`8f842dbba350821654c9dfed31f5635c`</div></div></td></tr><tr><td><div><div>`<ERROR_CODE>`</div><div>*Integer*</div></div></td><td><div><div>[Error code](/documentation/business-messaging/whatsapp/support/error-codes).</div></div></td><td><div><div>`131050`</div></div></td></tr><tr><td><div><div>`<ERROR_CODES_URL>`</div><div>*String*</div></div></td><td><div><div>Link to [error code documentation](/documentation/business-messaging/whatsapp/support/error-codes).</div></div></td><td><div><div>`/docs/whatsapp/cloud-api/support/error-codes/`</div></div></td></tr><tr><td><div><div>`<ERROR_DETAILS>`</div><div>*String*</div></div></td><td><div><div>[Error code](/documentation/business-messaging/whatsapp/support/error-codes) details.</div></div></td><td><div><div>`In order to maintain a healthy ecosystem engagement, the message failed to be delivered.`</div></div></td></tr><tr><td><div><div>`<ERROR_MESSAGE>`</div><div>*String*</div></div></td><td><div><div>[Error code](/documentation/business-messaging/whatsapp/support/error-codes) message. This value is the same as the `title` property value.</div></div></td><td><div><div>`This message was not delivered to maintain healthy ecosystem engagement.`</div></div></td></tr><tr><td><div><div>`<ERROR_TITLE>`</div><div>*String*</div></div></td><td><div><div>[Error code](/documentation/business-messaging/whatsapp/support/error-codes) title. This value is the same as the `message` property value.</div></div></td><td><div><div>`This message was not delivered to maintain healthy ecosystem engagement.`</div></div></td></tr><tr><td><div><div>`<GROUP_PARTICIPANT_USER_PHONE_NUMBER>`</div><div>*String*</div></div></td><td><div><div>WhatsApp user phone number. Property only included if message was sent to a [group](/books/meta-whatsapp/page/groups-api-developer-documentation).</div></div></td><td><div><div>`16505551234`</div></div></td></tr><tr><td><div><div>`<IDENTITY_KEY_HASH>`</div><div>*String*</div></div></td><td><div><div>Identity key hash. Only included if you have enabled the [identity change check](/books/meta-whatsapp/page/business-phone-numbers-developer-documentation) feature.</div></div></td><td><div><div>`DF2lS5v2W6x=`</div></div></td></tr><tr><td><div><div>`<IS_BILLABLE?>`</div><div>*Boolean*</div></div></td><td><div><div>Indicates if the message is billable (`true`) or not (`false`).</div><div>Note that the `billable` property will be deprecated in a future versioned release, so we recommend that you start using `pricing.type` and `pricing.category` together to determine if a message is billable, and if so, its billing rate.</div></div></td><td><div><div>`true`</div></div></td></tr><tr><td><div><div>`<PRICING_CATEGORY>`</div><div>*String*</div></div></td><td><div><div>Pricing category ([rate](/books/meta-whatsapp/page/pricing-on-the-whatsapp-business-platform-developer-documentation)) applied if billable. Values can be:</div><div>`authentication` — Indicates authentication rate applied.</div><div>`authentication-international` — Indicates authentication-international rate applied.</div><div>`marketing` — Indicates marketing rate applied.</div><div>`marketing_lite` — Indicates a [Marketing Messages API for WhatsApp](/books/meta-whatsapp/page/marketing-messages-api-for-whatsapp-developer-documentation) pricing applied.</div><div>`referral_conversion` — Indicates a [free entry point conversation](/books/meta-whatsapp/page/pricing-on-the-whatsapp-business-platform-developer-documentation).</div><div>`service` – Indicates service rate applied.</div><div>`utility` — Indicates utility rate applied.</div></div></td><td><div><div>`service`</div></div></td></tr><tr><td><div><div>`<PRICING_MODEL>`</div><div>*String*</div></div></td><td><div><div>Pricing model. Values can be:</div><div>`CBP` — Indicates conversation-based pricing applies. Will only be set to this value if the webhook was sent before July 1, 2025.</div><div>`PMP` — Indicates [per-message pricing](/books/meta-whatsapp/page/pricing-on-the-whatsapp-business-platform-developer-documentation) applies.</div></div></td><td><div><div>`PMP`</div></div></td></tr><tr><td><div><div>`<PRICING_TYPE>`</div><div>*String*</div></div></td><td><div><div>Pricing type.</div><div>`regular` — Indicates the message is billable.</div><div>`free_customer_service` — Indicates the message is free because it was either a utility template message or non-template message sent within a customer service window.</div><div>`free_entry_point` — Indicates the message is free because it was sent within an open free entry point window.</div></div></td><td><div><div>`regular`</div></div></td></tr><tr><td><div><div>`<STATUS>`</div><div>*String*</div></div></td><td><div><div>Message status. Values can be:</div><div>`delivered` — Indicates message was successfully delivered to the WhatsApp user’s device.</div><span>WhatsApp UI equivalent: Two checkmarks.</span><div>`failed` — Indicates failure to send or deliver the message to the WhatsApp user’s device.</div><span>WhatsApp UI equivalent: Red error triangle.</span><div>`played` — Indicates the first time a voice message is played by the WhatsApp user’s device.</div><span>WhatsApp UI equivalent: Blue microphone.</span><div>`read` — Indicates the message was displayed in an open chat thread in the WhatsApp user’s device.</div><span>WhatsApp UI equivalent: Two blue checkmarks.</span><div>`sent` — Indicates the message was successfully sent from our servers.</div><span>WhatsApp UI equivalent: One checkmark.</span></div></td><td><div><div>`read`</div></div></td></tr><tr><td><div><div>`<USER_PHONE_NUMBER_OR_GROUP_ID>`</div><div>*String*</div></div></td><td><div><div>WhatsApp user phone number or group ID.</div><div>Value set to the WhatsApp user’s phone number if the message was sent to their phone number, or set to a [group ID](/books/meta-whatsapp/page/groups-api-developer-documentation) if sent to a group ID. If sent to a group ID, the WhatsApp user’s phone number is instead assigned to the `recipient_participant_id` property.</div></div></td><td><div><div>`16505551234`</div></div></td></tr><tr><td><div><div>`<WEBHOOK_TRIGGER_TIMESTAMP>`</div><div>*String*</div></div></td><td><div><div>Unix timestamp indicating when the webhook was triggered.</div></div></td><td><div><div>`1739321024`</div></div></td></tr><tr><td><div><div>`<WHATSAPP_BUSINESS_ACCOUNT_ID>`</div><div>*String*</div></div></td><td><div><div>WhatsApp Business Account ID.</div></div></td><td><div><div>`102290129340398`</div></div></td></tr><tr><td><div><div>`<WHATSAPP_MESSAGE_ID>`</div><div>*String*</div></div></td><td><div><div>WhatsApp message ID.</div></div></td><td><div><div>`wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=`</div></div></td></tr></tbody></table>

</div></div>