Webhook
Push WhatsApp business events to the configured webhook URL (currently supports status callbacks and template button click callbacks).
- URL:
webhook_url
- Method:
POST
- Content-Type:
application/json
Status Callback
Delivery status for messages sent via WhatsApp API.
Response Parameters
Body parameters:
| Parameter |
Type |
Description |
| app_id |
String |
Application ID |
| business_phone |
String |
Business phone |
| channel |
Integer |
Channel type. WhatsApp is fixed to 2 |
| contacts |
array[contact Object] |
Contact information. It may be returned in status callbacks. Phone-number fields may be empty or omitted if the user uses anonymization. |
| merchant_phone |
String |
Merchant phone |
| messaging_product |
String |
Message type, fixed value "whatsapp" |
| metadata |
Object |
Merchant phone metadata |
| statuses |
array[status Object] |
Status list |
| wabaId |
String |
WABA ID |
- metadata object parameters:
| Parameter |
Type |
Description |
| display_phone_number |
String |
Merchant display phone number |
| phone_number_id |
String |
Merchant phone number ID |
- contact object parameters:
| Parameter |
Type |
Description |
| profile |
Object |
User profile. This field may be omitted. |
| wa_id |
String |
User phone number. This field may be empty or omitted if the user uses anonymization. |
| user_id |
String |
WhatsApp user BSUID. This field may be omitted if no BSUID is returned. |
| parent_user_id |
String |
If parent BSUID is enabled, this field is set to the user's parent BSUID. Otherwise, it is completely omitted. |
- profile object parameters:
| Parameter |
Type |
Description |
| name |
String |
WhatsApp user display name |
| username |
String |
Anonymized WhatsApp account. For sent status callbacks or users without anonymization enabled, this field is completely omitted. |
- status object parameters:
| Parameter |
Type |
Description |
| biz_opaque_callback_data |
String |
Tracking parameter carried when sending the message. This field may be omitted. |
| conversation |
Object |
Conversation info. It may be omitted for failed status callbacks. |
| errors |
array[error Object] |
Error info. Returned only for failure scenarios. |
| id |
String |
Message ID |
| meta_message_id |
String |
Original Meta message ID. This field may be omitted. When quoting a message, use meta_message_id as the referenced message ID if both id and meta_message_id exist; otherwise use id. |
| pricing |
Object |
Pricing model. It may be omitted for failed status callbacks. |
| recipient_id |
String |
User phone number. This field may be empty or omitted if the user uses anonymization. |
| recipient_user_id |
String |
If the message is sent to a user BSUID or parent BSUID, this field is set to that user BSUID or parent BSUID. Otherwise, it is omitted. |
| parent_recipient_user_id |
String |
If parent BSUID is enabled, this field is set to the user's parent BSUID. Otherwise, it is completely omitted. |
| timestamp |
String |
Callback timestamp |
| status |
String |
Message status: sent, delivered, read, failed, deleted |
| costs |
array[cost Object] |
Cost information. Usually returned for sent status callbacks. |
- conversation object parameters:
| Parameter |
Type |
Description |
| id |
String |
Conversation ID |
| expiration_timestamp |
String |
Conversation expiration timestamp. Usually returned for sent status callbacks. |
| origin |
Object |
Conversation type info |
- origin object parameters:
| Parameter |
Type |
Description |
| type |
String |
Conversation type, such as utility, marketing, authentication, service, referral_conversion, marketing_lite |
- pricing object parameters:
| Parameter |
Type |
Description |
| billable |
boolean |
Whether the message is billable |
| category |
String |
Pricing category, such as utility, marketing, authentication, service, referral_conversion, marketing_lite |
| pricing_model |
String |
Pricing model, such as PMP or CBP |
| type |
String |
Pricing type, such as regular, free_customer_service, free_entry_point |
| Parameter |
Type |
Description |
| cdr_type |
Integer |
CDR type: 1 message, 4 marketing session, 5 notification session, 6 verification session, 7 service session, 8 free session, 9 international verification, 10 MM Lite Api |
| currency |
String |
Currency |
| direction |
Integer |
Direction: 1 downlink, 2 uplink |
| foreign_price |
number |
Customer price in customer currency |
| message_id |
String |
WA message ID |
| price |
number |
Platform settlement price. This field may be omitted. |
| Parameter |
Type |
Description |
| code |
Integer |
Error code |
| meta_code |
Integer |
Meta error code. This field may be omitted. |
| title |
String |
Error message |
Anonymization Field Notes
When a user has anonymization enabled, phone-number fields in the status callback may be omitted:
recipient_id: user phone number; may be empty or omitted after anonymization.contacts[].wa_id: user phone number; may be empty or omitted after anonymization.recipient_user_id / contacts[].user_id: user BSUID. If the message is sent using a BSUID or parent BSUID, the callback returns the corresponding value.parent_recipient_user_id / contacts[].parent_user_id: parent BSUID. Returned only when parent BSUID is enabled.contacts[].profile.username: anonymized account. Omitted for sent status callbacks or users without anonymization enabled.
Response Examples
Message Sent
{
"app_id": "547",
"business_phone": "62895303xxxx",
"channel": 2,
"contacts": [
{
"user_id": "US.36196856xxxx4656",
"wa_id": "1859967xxxx"
}
],
"merchant_phone": "62895303xxxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "62895303xxxx",
"phone_number_id": "1034730xxxxx9406"
},
"statuses": [
{
"biz_opaque_callback_data": "NX_AI_SOURCE",
"conversation": {
"expiration_timestamp": "1780904196",
"id": "3776abb4f63181b0ba423a556f6xxxx",
"origin": {
"type": "utility"
}
},
"costs": [
{
"cdr_type": 5,
"currency": "USD",
"direction": 1,
"foreign_price": 0.0000,
"message_id": "wamid.HBgLMTg1OTk2Nzk3OTQVAgARGBI2RDd...",
"price": 0.0000
}
],
"id": "NX_AI_SOURCE-1cfaf78ac39041d58e14d80fxxxx",
"meta_message_id": "wamid.HBgLMTg1OTk2Nzk3OTQVAgARGBI2RDd...",
"pricing": {
"billable": true,
"category": "utility",
"pricing_model": "PMP",
"type": "regular"
},
"recipient_id": "1859967xxxx",
"recipient_user_id": "US.36196856xxxx4656",
"status": "sent",
"timestamp": "1780904196"
}
],
"wabaId": "1007605xxxxx6973"
}
Message Delivered
{
"app_id": "547",
"business_phone": "62895303xxxx",
"channel": 2,
"contacts": [
{
"user_id": "DE.36196866xxxx4557",
"wa_id": "4917766xxxx"
}
],
"merchant_phone": "62895303xxxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "62895303xxxx",
"phone_number_id": "1034730xxxxx9406"
},
"statuses": [
{
"biz_opaque_callback_data": "NX_AI_SOURCE",
"conversation": {
"id": "d826cad84c494a0922d709751dxxxx",
"origin": {
"type": "utility"
}
},
"id": "NX_AI_SOURCE-0b67fa1a357a4193a6ce1d25xxxx",
"meta_message_id": "wamid.HBgMNDkxNzc2Njk4NTM2FQIAERgSNkUw...",
"pricing": {
"billable": true,
"category": "utility",
"pricing_model": "PMP",
"type": "regular"
},
"recipient_id": "4917766xxxx",
"recipient_user_id": "DE.36196866xxxx4557",
"status": "delivered",
"timestamp": "1780904268"
}
],
"wabaId": "1007605xxxxx6973"
}
Message Read
{
"app_id": "433",
"business_phone": "9665356xxxx",
"channel": 2,
"contacts": [
{
"user_id": "SA.13082051xxxx8477",
"wa_id": "9665984xxxx"
}
],
"merchant_phone": "9665356xxxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "9665356xxxx",
"phone_number_id": "2159038xxxxx0007"
},
"statuses": [
{
"biz_opaque_callback_data": "NX_AI_SOURCE",
"conversation": {
"id": "683b09b74d09aed49ad8b02ac4xxxx",
"origin": {
"type": "utility"
}
},
"id": "NX_AI_SOURCE-7af1311983974721b8854d72xxxx",
"meta_message_id": "wamid.HBgMOTY2NTk4NDk5NzUyFQIAERgSNUM0...",
"pricing": {
"billable": true,
"category": "utility",
"pricing_model": "PMP",
"type": "regular"
},
"recipient_id": "9665984xxxx",
"recipient_user_id": "SA.13082051xxxx8477",
"status": "read",
"timestamp": "1780904326"
}
],
"wabaId": "2574232xxxxx9503"
}
Message Failed
{
"app_id": "547",
"business_phone": "62895303xxxx",
"channel": 2,
"contacts": [
{
"wa_id": "1775391xxxx"
}
],
"merchant_phone": "62895303xxxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "62895303xxxx",
"phone_number_id": "1034730xxxxx9406"
},
"statuses": [
{
"biz_opaque_callback_data": "NX_AI_SOURCE",
"errors": [
{
"code": 131026,
"title": "Message undeliverable"
}
],
"id": "NX_AI_SOURCE-c0c971b05dbc448b94ccb77dxxxx",
"meta_message_id": "wamid.HBgLMTc3NTM5MTczNzgVAgARGBI0OEY...",
"recipient_id": "1775391xxxx",
"status": "failed",
"timestamp": "1780904362"
}
],
"wabaId": "1007605xxxxx6973"
}
Message Deleted
The deleted status keeps the historical compatibility format. Actual fields depend on the callback payload returned.
{
"statuses": [
{
"id": "ID",
"recipient_id": "WHATSAPP_ID",
"status": "deleted",
"timestamp": "TIMESTAMP",
"type": "message",
"message": {
"recipient_id": "WHATSAPP_ID"
}
}
]
}
Template Button Click Callback
Button click callbacks for template messages (only quick-reply buttons are supported).
Response Parameters
Body parameters:
| Parameter |
Type |
Description |
| contacts |
array[contact JsonObject] |
Contact info |
| messages |
array[message JsonObject] |
Callback info |
| business_phone |
String |
Business phone |
| messaging_product |
String |
Message type, fixed value "whatsapp" |
- contact object parameters:
| Parameter |
Type |
Description |
| profile |
object |
Contact profile |
| wa_id |
String |
WhatsApp ID |
- profile object parameters:
| Parameter |
Type |
Description |
| name |
String |
Name |
- message object parameters:
| Parameter |
Type |
Description |
| context |
JsonObject |
Context |
| from |
String |
Sender WhatsApp ID |
| id |
String |
Message ID |
| timestamp |
String |
Timestamp |
| type |
String |
Message type (button) |
| button |
JsonObject |
Button info |
- context object parameters:
| Parameter |
Type |
Description |
| from |
String |
Sender WhatsApp ID |
| id |
String |
Original message ID |
- button object parameters:
| Parameter |
Type |
Description |
| text |
String |
Button text |
| payload |
String |
Button payload |
Response Example
{
"contacts": [
{
"profile": {
"name": "Uxxxxx"
},
"wa_id": "86186xxxxx"
}
],
"messages": [
{
"context": {
"from": "86186xxxxx",
"id": "wamid.HBgNNjg2xxxxx"
},
"from": "86186xxxxx",
"id": "wamid.HBgNNjg2xxxxx",
"timestamp": "1669686240",
"type": "button",
"button": {
"payload": "Quick reply button payload",
"text": "Quick reply button text"
}
}
],
"business_phone": "86158xxxxx",
"messaging_product": "whatsapp"
}