Webhook
For the provided webhook URL, it supports the delivery of WhatsApp-related push messages for Status Reply and Message Reply and Template status update, WABA account update in the WhatsApp business context.
- URL:
webhook_url
- Method:
POST
- Content-Type:
application/json
Status Reply
For scenarios where messages are sent using the WhatsApp API, it provides the delivery status of the messages.
Response Parameters
Body parameters:
| Parameter Name |
Type |
Description |
| statuses |
array of status JsonObject |
Result code |
| business_phone |
String |
Business phone number |
| messaging_product |
String |
Message type, fixed value "whatsapp" |
- status object parameters:
| Parameter Name |
Type |
Description |
| conversation |
JsonObject |
Conversation information |
| errors |
array of error JsonObject |
Error information |
| recipient_id |
String |
Recipient's WhatsApp ID |
| timestamp |
String |
Callback timestamp |
| status |
String |
Message status: sent, delivered, read, failed, deleted |
| id |
String |
Message ID |
| costs |
array of cost object |
Cost information |
| pricing |
JsonObject |
pricing model |
- conversation object parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Conversation ID |
| expiration_timestamp |
String |
Conversation expiration timestamp |
| origin |
JsonObject |
Conversation type information |
| 参数名 |
类型 |
说明 |
| billable |
boolean |
false/true |
| category |
String |
- authentication — indicates an authentication template message.- authentication_international – indicates an authentication template message sent to a WhatsApp user in a country or region that has authentication-international rates.- marketing — indicates a marketing template message.- marketing_lite — indicates a marketing template sent via Marketing Messages Lite API.- utility — indicates a utility template message.- service — indicates a non-template message.- referral_conversion — indicates the message is part of a free entry point conversation. |
| pricing_model |
String |
"PMP" — indicates per-message pricing applies."CBP" — indicates conversation-based pricing applies; will only be set to this value if the webhook is for a message that is part of a free entry point conversation, and only if the message was sent prior to July 1, 2025. |
| type |
String |
regular — indicates the message is billable.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.free_entry_point — indicates the message is free because it is part of a free-entry point conversation. |
- origin object parameters:
| Parameter Name |
Type |
Description |
| type |
String |
Conversation type |
"marketing": "(Effective from June 1, 2023) Merchants initiate conversations using message templates marked as MARKETING", corresponding to direction=4 (marketing)
"utility": "(Effective from June 1, 2023) Merchants initiate conversations using message templates marked as UTILITY", corresponding to direction=5 (notification)
"authentication": "(Effective from June 1, 2023) Merchants initiate conversations using message templates marked as AUTHENTICATION", corresponding to direction=6 (authentication)
"service": "(Effective from June 1, 2023) Users initiate conversations", corresponding to direction=7 (service)
"referral_conversion": "(Effective from June 1, 2023) (Free) Users initiate conversations by clicking on WhatsApp ads or Facebook Page call-to-action buttons", corresponding to direction=8 (free conversation)
"marketing_lite": "MM Lite API conversations"
| Parameter Name |
Type |
Description |
| code |
Integer |
Error code |
| meta_code |
Integer |
Meta Error code |
| title |
String |
Error message |
| Parameter Name |
Type |
Description |
| currency |
String |
Currency |
| price |
number |
Customer price (local currency CNY) |
| foreign_price |
number |
Customer price (foreign currency) |
| cdr_type |
Integer |
CDR type, starting from June 1, 2023, using 4 (marketing), 5 (notification), 6 (authentication), 7 (service), 8 (free conversation) |
| message_id |
String |
WhatsApp message ID |
| direction |
Integer |
Direction, 1 (outbound), 2 (inbound) |
Response Example
Message Sent
{
"app_id": "48",
"business_phone": "xxx",
"channel": 2,
"merchant_phone": "xxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"statuses": [
{
"conversation": {
"expiration_timestamp": "1750644366",
"id": "f9df70c0f6ec5413e57ff99d51792e41",
"origin": {
"type": "marketing"
}
},
"costs": [
{
"cdr_type": 4,
"currency": "CNY",
"direction": 1,
"foreign_price": 11,
"message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjA2RDk1OThCMkJGQ0FFRDJERQA=",
"price": 1.5444
}
],
"id": "wamid.b6caa84cad3c401090640edf0eff7fa3",
"meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjA2RDk1OThCMkJGQ0FFRDJERQA=",
"pricing": {
"billable": true,
"category": "marketing",
"pricing_model": "PMP",
"type": "regular"
},
"recipient_id": "xxx",
"status": "sent",
"timestamp": "1750644366"
}
],
"wabaId": "xxx"
}
Message Delivered
{
"app_id": "48",
"business_phone": "xxx",
"channel": 2,
"merchant_phone": "xxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "661162737077678"
},
"statuses": [
{
"conversation": {
"id": "e0eea618562a40f99211ea617241b784",
"origin": {
"type": "marketing"
}
},
"id": "wamid.b3316b3b6d7c4dfd8f1a077aa8787140",
"meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjgwQ0Q4NTk1Q0I4RkZDMjlEMAA=",
"pricing": {
"billable": true,
"category": "marketing",
"pricing_model": "PMP",
"type": "regular"
},
"recipient_id": "xxx",
"status": "delivered",
"timestamp": "1750644491"
}
],
"wabaId": "xxx"
}
Message Read
{
"app_id": "48",
"business_phone": "xxx",
"channel": 2,
"merchant_phone": "xxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"statuses": [
{
"conversation": {
"id": "e0eea618562a40f99211ea617241b784",
"origin": {
"type": "marketing"
}
},
"id": "wamid.b3316b3b6d7c4dfd8f1a077aa8787140",
"meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYEjgwQ0Q4NTk1Q0I4RkZDMjlEMAA=",
"pricing": {
"billable": true,
"category": "marketing",
"pricing_model": "PMP",
"type": "regular"
},
"recipient_id": "xxx",
"status": "delivered",
"timestamp": "1750644491"
}
],
"wabaId": "xxx"
}
Message sending failed
Error code description
| code |
message |
solution |
| 9001 |
System business error |
Platform error, please contact relevant personnel for troubleshooting |
| 10000 |
Meta Error |
WhatsApp official sending error, please refer to meta_code, title for details |
| 10001 |
Wa Engine Error |
WhatsApp-Engine upstream error, please contact relevant personnel to troubleshoot |
| 10002 |
Wa Engine Send Message Timeout |
WhatsApp-Engine sending timeout, please contact relevant personnel to troubleshoot |
Send Meta Failed
{
"business_phone": "xxx",
"messaging_product": "whatsapp",
"statuses": [
{
"errors": [
{
"code": 10000,
"meta_code": 132001,
"title": "Meta Error((#132001) Template name does not exist in the translation)"
}
],
"id": "wamid.e5d9f560d762417093b20632f959edaf",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754379719"
}
],
"wabaId": "xxx"
}
{
"business_phone": "xxx",
"messaging_product": "whatsapp",
"statuses": [
{
"errors": [
{
"code": 10000,
"meta_code": 132005,
"title": "Meta Error((#132005) Translated text too long)"
}
],
"id": "wamid.20250805065001002957",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754347801"
}
],
"wabaId": "xxx"
}
{
"business_phone": "xxx",
"messaging_product": "whatsapp",
"statuses": [
{
"errors": [
{
"code": 10000,
"meta_code": 131009,
"title": "Meta Error((#131009) Parameter value is not valid)"
}
],
"id": "wamid.aee91da808384646801081988e407f26",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754373435"
}
],
"wabaId": "xxx"
}
{
"business_phone": "xxx",
"messaging_product": "whatsapp",
"statuses": [
{
"errors": [
{
"code": 10000,
"meta_code": 100,
"title": "Meta Error((#100) Invalid parameter)"
}
],
"id": "wamid.519617086f75439885db384697910fb9",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754379958"
}
],
"wabaId": "xxx"
}
{
"business_phone": "xxx",
"messaging_product": "whatsapp",
"statuses": [
{
"errors": [
{
"code": 10000,
"meta_code": 131056,
"title": "Meta Error((#131056) (Business Account, Consumer Account) pair rate limit hit)"
}
],
"id": "wamid.6d848cd539254caf94feeae5baf186c0",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754379592"
}
],
"wabaId": "xxx"
}
Meta Webhook Failed
{
"app_id": "1109",
"business_phone": "xxx",
"channel": 2,
"merchant_phone": "xxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"statuses": [
{
"errors": [
{
"code": 131026,
"title": "Message undeliverable"
}
],
"id": "wamid.9fd734dfdde54a14bcef35a907d36da5",
"meta_message_id": "wamid.HBgNNjI4NTI1MDE2NTI1MxUCABEYEjFCNjQzNDc1NTA1NzY2QjVDMQA=",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754380417"
}
],
"wabaId": "xxx"
}
{
"app_id": "547",
"business_phone": "xxx",
"channel": 2,
"merchant_phone": "xxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"statuses": [
{
"errors": [
{
"code": 131053,
"title": "Media upload error"
}
],
"id": "wamid.40ab29af312f4f8b8ba96c231d55a96e",
"meta_message_id": "wamid.HBgLNDg2Njk5Njk4ODUVAgARGBJDQUNDQkQ2QTg4NjA1MEQxRUEA",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754379976"
}
],
"wabaId": "xxx"
}
{
"app_id": "456",
"business_phone": "xxx",
"channel": 2,
"merchant_phone": "xxx",
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"statuses": [
{
"errors": [
{
"code": 131047,
"href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/",
"title": "Re-engagement message"
}
],
"id": "wamid.084034bfd79e42d1b97dc387c4abbcd0",
"meta_message_id": "wamid.HBgLNjAxOTg1NTg5OTMVAgARGBI4RDFFMTM0MEE0MkUwNDdFM0QA",
"recipient_id": "xxx",
"status": "failed",
"timestamp": "1754380547"
}
],
"wabaId": "xxx"
}
Message Reply
For scenarios where WhatsApp users send messages to merchant numbers, it provides the push of inbound message information.
Response Parameters
Body parameters:
| Parameter Name |
Type |
Description |
| contacts |
array of contact JsonObject |
Contact information |
| messages |
array of message JsonObject |
Inbound messages |
| business_phone |
String |
Business phone number |
| messaging_product |
String |
Message type, fixed value "whatsapp" |
- contact object parameters:
| Parameter Name |
Type |
Description |
| profile |
JsonObject |
Profile object |
| wa_id |
String |
Contact's WhatsApp ID |
- profile object parameters:
| Parameter Name |
Type |
Description |
| name |
String |
Profile name |
- message object parameters:
| Parameter Name |
Type |
Description |
| from |
String |
Sender's WhatsApp ID |
| id |
String |
Message identifier, this ID can be used to mark the message as read |
| timestamp |
String |
Message receive timestamp |
| type |
String |
Supported message types:1. text2. image3. video4. voice5. audio6. document7. location8. sticker 9. interactive 10. order 11.referral 12.reaction |
| context |
JsonObject |
Only exists if the user replies to or interacts with one of your messages |
| cost |
JsonObject |
Cost information |
| Parameter Name |
Type |
Description |
| currency |
String |
Currency |
| price |
number |
Customer price (local currency CNY) |
| foreign_price |
number |
Customer price (foreign currency) |
| cdr_type |
Integer |
CDR type, 4 (marketing), 5 (notification), 6 (authentication), 7 (service), 8 (advertisement promotion) |
| message_id |
String |
WhatsApp message ID |
| direction |
Integer |
Direction, 1 (outbound), 2 (inbound) |
- Text Message Parameters:
| Parameter Name |
Type |
Description |
| body |
String |
Message text |
- Image Message Parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Media storage ID, can be used to retrieve media URL |
| caption |
String |
Image caption |
| mime_type |
String |
MIME type of the media file |
| sha256 |
String |
Checksum signature of the media file |
| link |
String |
Media link.expire 48 hour |
- Video Message Parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Media storage ID, can be used to retrieve media URL |
| caption |
String |
Video caption |
| mime_type |
String |
MIME type of the media file |
| sha256 |
String |
Checksum signature of the media file |
| link |
String |
Media link.expire 48 hour |
- Voice Message Parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Media storage ID, can be used to retrieve media URL |
| mime_type |
String |
MIME type of the media file |
| sha256 |
String |
Checksum signature of the media file |
| link |
String |
Media link.expire 48 hour |
- Audio Message Parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Media storage ID, can be used to retrieve media URL |
| mime_type |
String |
MIME type of the media file |
| sha256 |
String |
Checksum signature of the media file |
| link |
String |
Media link.expire 48 hour |
- Document Message Parameters:
| Parameter Name |
Type |
Description |
| document |
JsonObject |
Refer to response example Document message content, available when type=document |
- document object parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Media storage ID, can be used to retrieve media URL |
| mime_type |
String |
MIME type of the media file |
| sha256 |
String |
Checksum signature of the media file |
| filename |
String |
Document file name |
| link |
String |
Media link.expire 48 hour |
- Location Message Parameters:
| Parameter Name |
Type |
Description |
| location |
JsonObject |
Refer to response example Location message content, available when type=location |
- location object parameters:
| Parameter Name |
Type |
Description |
| longitude |
String |
Longitude information of the location |
| latitude |
String |
Latitude information of the location |
| name |
String |
Name of the location |
| address |
String |
Detailed address information of the location |
- Sticker Message Parameters:
| Parameter Name |
Type |
Description |
| sticker |
JsonObject |
Refer to response example Sticker message content, available when type=sticker |
- sticker object parameters:
| Parameter Name |
Type |
Description |
| id |
String |
Media storage ID, can be used to retrieve media URL |
| link |
String |
Media link.expire 48 hour |
- Interactive Message Parameters:
- interactive object parameters:
| Parameter Name |
Type |
Description |
| type |
String |
button_reply (button reply) list_reply (list reply) nfm_reply (form submission) |
| button_reply |
JsonObject |
Sent when a customer clicks a button, an object with this property. |
| list_reply |
JsonObject |
Sent when a client selects an item from the list, an object with this property. |
| nfm_reply |
JsonObject |
|
- button_reply OR list_reply object parameters：
| Parameter Name |
Type |
Description |
| id |
String |
Button ID |
| title |
String |
title |
| description |
String |
Option description, only for list_reply |
- nfm_reply object parameters：
| Parameter Name |
Type |
Description |
| name |
String |
Fixed to flow |
| body |
String |
Text after message submission |
| response_json |
String |
JSON data of flow.. The structure is either defined in flow JSON (see Complete action) or, if flow is using an endpoint, controlled by endpoint (see Final Response Payload in Data Exchange Request) |
- Order Message Parameters:
| Parameter Name | Type | Description |
| catalog_id | String | catelog ID |
| text | String | Sent when a customer clicks a button, an object with this property. |
| product_items | Array[JsonObject] | Sent when a client selects an item from the list, an object with this property. |
- product_items object parameters：
| Parameter Name | Type | Description |
| product_retailer_id | String | Unique identifier for the product in the catalog |
| quantity | Number | Item quantity |
| item_price | Number | Price per item |
| currency | String | Currency Type |
- referral Message Parameters:
- context object parameters：
| Parameter Name |
Type |
Description |
| from |
String |
Source number cited |
| id |
String |
Message ID |
| meta_message_id |
String |
meta message id (may not exist) |
| forwarded |
Boolean |
Set to true if the message received by the merchant has been forwarded |
| frequently_forwarded |
Boolean |
Set to true if the message received by the merchant has been forwarded more than 5 times. |
| referred_product |
JsonObject |
This object is included when quoting a reply to a product message |
- referred_product object parameters：
| Parameter Name |
Type |
Description |
| catalog_id |
String |
catalog id |
| product_retailer_id |
String |
Unique identifier for the product in the catalog |
- advertisement to introduce customer message parameters:
| Parameter Name |
Type |
Description |
| referral |
JsonObject |
Message response example When a customer clicks on an ad and the ad redirects them to WhatsApp, this object is included in the message object |
- referral object parameters：
| Parameter Name |
Type |
Description |
| source_url |
String |
Meta URL pointing to the ad or post that the customer clicked.Opening this URL will show the ad from the customer's perspective. |
| source_type |
String |
Meta ID of the ad or post |
| headline |
String |
The title used in the ad or post |
| body |
String |
The body of the ad or post |
| media_type |
String |
The type of media present in the ad or post; image or video |
| image_url |
String |
Image URL when the media type is image |
| video_url |
String |
When the media type is video, the video URL |
| thumbnail_url |
String |
Thumbnail URL when the media type is video |
| ctwa_clid |
String |
Click ID generated by Meta for click-to-WhatsApp ads |
- reaction message parameters:
| Parameter Name |
Type |
Example Value |
Description |
| reaction |
JsonObject |
See request example |
reaction message content, type=reaction is required |
- reaction object parameters：
| Parameter Name |
Type |
required |
Description |
| meta_message_id |
String |
yes |
meta message id |
| message_id |
String |
yes |
Message reply id, for example: wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYEkVCQkE4NjdGRUE5RDgyQzg0RAA= |
| emoji |
String |
yes |
Emoticons Example: "❤️" |
Response Example
Text Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
"text": {
"body": "Hello"
},
"timestamp": "1663053831",
"type": "text",
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQNkLO2ipL1_ZpZ41mwgMHEg",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Image Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQk5kC-xMSoi3XpEwoF2ZkIg",
"image": {
"id": "2bc7102f-5491-40b1-a92f-338303eab9d3",
"mime_type": "image/jpeg",
"sha256": "0ed3d9d4db83ed7751314af5f2e9bf008edc49a101bebb9054a97f824cf2136b",
"link":"https://dd.xx"
},
"timestamp": "1663053029",
"type": "image",
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQk5kC-xMSoi3XpEwoF2ZkIg",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Video Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQysyxXFholwoQ-lCwUTTWfw",
"timestamp": "1663054466",
"type": "video",
"video": {
"id": "bfc0619d-995e-49da-9869-e911a34c43b9",
"mime_type": "video/mp4",
"sha256": "e0ceec95f44fec6282ab02f947ee92dbe481dacf0478618a997580a822acc88b",
"link":"https://dd.xx"
},
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQysyxXFholwoQ-lCwUTTWfw",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Voice Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQyrJn0a5IBKlmHZqf_uAuFw",
"timestamp": "1663055136",
"type": "voice",
"voice": {
"id": "25fdf335-d846-4e6c-9aa8-35f25abc564c",
"mime_type": "audio/ogg; codecs=opus",
"sha256": "f321ac774459c50e376048d6f2c02fc2c14f13be85c5e52a67ec16a358b34de7",
"link":"https://dd.xx"
},
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQyrJn0a5IBKlmHZqf_uAuFw",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Audio Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"audio": {
"id": "aab95384-fc19-4136-a330-97e1f8a4cb02",
"mime_type": "audio/mpeg",
"sha256": "9a73ab6362694fba48a5027c8443ceb34838009601ce480d85f08c600cf520f1",
"link":"https://dd.xx"
},
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQdSLi6R7UCDSsCqNkjrtczg",
"timestamp": "1663053098",
"type": "audio",
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQdSLi6R7UCDSsCqNkjrtczg",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx819",
"messaging_product": "whatsapp"
}
Document Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"document": {
"caption": "null.txt",
"filename": "null.txt",
"id": "806bb2f3-d8cc-4477-8b4d-d89df862f6c0",
"mime_type": "text/plain",
"sha256": "90c7bd7c509aa1d68c09a67b9ba2d17022a6861681fbd75c8845ee48193e8646",
"link":"https://dd.xx"
},
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQGvyQjDNptdnjvjN0dkD90Q",
"timestamp": "1663052759",
"type": "document",
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQGvyQjDNptdnjvjN0dkD90Q",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Location Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQO8HTCPOtJUZLNLRo2dPufw",
"location": {
"address": "Shenzhen, Guangdong",
"latitude": 22.550802897696343,
"longitude": 113.93844723701477,
"name": "KFC",
"url": "http://www.kfc.com.cn"
},
"timestamp": "1663053163",
"type": "location",
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQO8HTCPOtJUZLNLRo2dPufw",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Sticker Message Response Example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "86176xxxx0819"
}
],
"messages": [
{
"from": "86176xxxx0819",
"id": "ABGHhhdgYFCBnwIQ1kuKFSU5LfuDxSUPOjKIwA",
"sticker": {
"id": "1b0a4c77-c5e7-44fa-b2a3-b69941ed3c64",
"metadata": {
"emojis": [
"☕",
"🙂"
],
"is-first-party-sticker": 1,
"sticker-pack-id": "whatsappcuppy"
},
"mime_type": "image/webp",
"sha256": "98267fedaeac67a4cc6b5e18a2444249fba5b6363a690115139675d53a63b0ff",
"link":"https://dd.xx"
},
"timestamp": "1663054803",
"type": "sticker",
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 4,
"message_id": "ABGHhhdgYFCBnwIQ1kuKFSU5LfuDxSUPOjKIwA",
"direction": 1
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Interactive quick reply example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "852xxxx705"
}
],
"messages": [
{
"context": {
"from": "86176xxxx0819",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGBJDNDI1ODA3QzE0NkEwMUY1NjQA"
},
"from": "852xxxx705",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTc1OEVGOEFBQ0U4QkIwNzFCOQA=",
"timestamp": "1701849537",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "2",
"title": "不愿意"
}
},
"cost": {
"currency": "CNY",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTc1OEVGOEFBQ0U4QkIwNzFCOQA=",
"direction": 2
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Interactive message list example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "852xxxx705"
}
],
"messages": [
{
"context": {
"from": "86176xxxx0819",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGBI2NDFBRDA4NzcyOUU3NUJDODIA"
},
"from": "852xxxx705",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQUVGMzA0MDM0QUZGRUJGOTRCMgA=",
"timestamp": "1701850329",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "2",
"title": "牛肉面",
"description": "红烧牛肉面"
}
},
"cost": {
"currency": "CNY",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQUVGMzA0MDM0QUZGRUJGOTRCMgA=",
"direction": 2
}
}
]
,
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Order message response example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "852xxxx705"
}
],
"messages": [
{
"from": "852xxxx705",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTJEQ0M5MEM0OURFNjZDQjY0MQA=",
"timestamp": "1701847162",
"type": "order",
"order": {
"catalog_id": "310639698193384",
"text": "",
"product_items": [
{
"product_retailer_id": "h0v6snwgg6",
"quantity": 1.0,
"item_price": 124.0,
"currency": "CNY"
},
{
"product_retailer_id": "qnp7xflxk9",
"quantity": 1.0,
"item_price": 1000.0,
"currency": "CNY"
}
]
},
"cost": {
"currency": "CNY",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTJEQ0M5MEM0OURFNjZDQjY0MQA=",
"direction": 2
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Product message example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "852xxxx705"
}
],
"messages": [
{
"context": {
"from": "86176xxxx0819",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgARGA9wcm9kdWN0X2lucXVpcnkA",
"referred_product": {
"catalog_id": "310639698193384",
"product_retailer_id": "qnp7xflxk9"
}
},
"from": "852xxxx705",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTQ0MEI2Rjc4MURCM0VFOTQwMwA=",
"timestamp": "1701846846",
"type": "text",
"text": {
"body": "I want."
},
"cost": {
"currency": "CNY",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTQ0MEI2Rjc4MURCM0VFOTQwMwA=",
"direction": 2
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Quote message example
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "852xxxx705"
}
],
"messages": [
{
"from": "852xxxx705",
"id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTJEQ0M5MEM0OURFNjZDQjY0MQA=",
"timestamp": "1701847162",
"type": "order",
"order": {
"catalog_id": "310639698193384",
"text": "",
"product_items": [
{
"product_retailer_id": "h0v6snwgg6",
"quantity": 1.0,
"item_price": 124.0,
"currency": "CNY"
},
{
"product_retailer_id": "qnp7xflxk9",
"quantity": 1.0,
"item_price": 1000.0,
"currency": "CNY"
}
]
},
"cost": {
"currency": "CNY",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgLODUyNTUzMTE3MDUVAgASGBQzQTJEQ0M5MEM0OURFNjZDQjY0MQA=",
"direction": 2
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Message example for ad referrals
{
"contacts": [
{
"profile": {
"name": "Jay"
},
"wa_id": "852xxxx705"
}
],
"messages": [
{
"from": "852xxxx705",
"id": "wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYIDM3REYzQUZEMzQ5MDY1RkYxQjg4NEY0NURBMjg3QUIxAA==",
"timestamp": "1700222189",
"type": "text",
"text": {
"body": "Hi, I would like to know more information."
},
"referral": {
"headline": "Chat with us",
"source_type": "ad",
"source_id": "120200744305620497",
"source_url": "https://fb.me/6cf1tN8rT"
},
"cost": {
"currency": "USD",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYIDM3REYzQUZEMzQ5MDY1RkYxQjg4NEY0NURBMjg3QUIxAA==",
"direction": 2
}
}
],
"merchant_phone": "86176xxxx0819",
"messaging_product": "whatsapp"
}
Reaction-message-example
{
"messaging_product": "whatsapp",
"contacts": [
{
"wa_id": "8617xxxx50819",
"profile": {
"name": "Jay"
}
}
],
"messages": [
{
"from": "8617xxxx50819",
"id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABISVASBMzBDMjVFNkIxRUFGMzAzNTREAA==",
"timestamp": "1724118060",
"type": "reaction",
"reaction": {
"message_id": "wamid.4092fc1a7877448f8ec8c8d2216dfdd4",
"meta_message_id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABISVASBMzBDMjVFNkIxRUFGMzAzNTREAA=",
"emoji": "👍"
},
"cost": {
"currency": "CNY",
"price": 0,
"foreign_price": 0,
"cdr_type": 1,
"message_id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABISVASBMzBDMjVFNkIxRUFGMzAzNTREAA==",
"direction": 2
}
}
],
"metadata": {
"display_phone_number": "8523xxxx859",
"phone_number_id": "12487xxxxx14609"
},
"app_id": "48",
"business_phone": "8523xxxx859",
"merchant_phone": "8523xxxx859",
"channel": 2
}
Template status update
Template approved
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "APPROVED",
"time": 1713313467,
"message_template_id": "1370101990353470",
"message_template_name": "lostgreethungarian20",
"message_template_language": "hu",
"reason": "NONE"
},
"field": "message_template_status_update"
}
Template rejected
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "REJECTED",
"time": 1713165587,
"message_template_id": "1084366229523542",
"message_template_name": "mulanfreeen",
"message_template_language": "en",
"reason": "INCORRECT_CATEGORY"
},
"field": "message_template_status_update"
}
Templates scheduled to be disabled
{
"field": "message_template_status_update",
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "FLAGGED",
"message_template_id": "TEMPLATE-ID",
"message_template_name": "My message template",
"message_template_language": "en-US",
"reason": null,
"disable_info": {
"disable_date": "DATE",
}
}
Template is paused
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "PAUSED",
"message_template_id": 6048,
"message_template_name": "welcome",
"message_template_language": "en_US",
"reason": "NONE",
"other_info": {
"title": "SECOND_PAUSE",
"description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues."
}
},
"field": "message_template_status_update"
}
Template message to be deleted
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "PENDING_DELETION",
"message_template_id": 1137,
"message_template_name": "<MY_TEMPLATE_NAME>",
"message_template_language": "en_US",
"reason": "NONE"
},
"field": "message_template_status_update"
}
Template quality update
{
"value": {
"business_phone": "852xxxx3867",
"time": 1730390145,
"message_template_id": "301336xxxx511624",
"message_template_name": "simon_def2",
"message_template_language": "en_US",
"previous_quality_score": "UNKNOWN",
"new_quality_score": "YELLOW",
"wabaId": "10903xxxxxx0925"
},
"field": "message_template_quality_update"
}
Template category update
{
"field": "template_category_update",
"value": {
"business_phone": "8523***859",
"message_template_id": "138641***878",
"message_template_language": "zh_CN",
"message_template_name": "test_service_1",
"new_category": "MARKETING",
"time": 1745385279,
"wabaId": "1386417***78"
}
}
{
"field": "template_category_update",
"value": {
"business_phone": "8523****59",
"message_template_id": "13864****7878",
"message_template_language": "zh_CN",
"message_template_name": "test_service_1",
"new_category": "MARKETING",
"previous_category": "UTILITY",
"time": 1745385279,
"wabaId": "13864****878"
}
}
WABA account update
Sandbox number upgraded to verified account
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"phone_number": "PHONE_NUMBER",
"event": "VERIFIED_ACCOUNT"
},
"field": "account_update"
}
WhatsApp business account banned
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "DISABLED_UPDATE",
"ban_info": {
"waba_ban_state": [
"SCHEDULE_FOR_DISABLE",
"DISABLE",
"REINSTATE"
],
"waba_ban_date": "DATE"
}
},
"field": "account_update"
}
WhatsApp business account policy violation
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "ACCOUNT_VIOLATION",
"violation_info": {
"violation_type": "VIOLATION_TYPE"
}
},
"field": "account_update"
}
WhatsApp Business account restricted due to policy violation
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"event": "ACCOUNT_RESTRICTION",
"restriction_info": [
{
"restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING" | "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION"| "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
"expiration": "TIMESTAMP"
}
]
},
"field": "account_update"
}
WhatsApp business account review completed
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"decision": "APPROVED"
},
"field": "account_review_update"
}
WhatsApp business account deleted
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"phone_number": "1669xxxx193",
"event": "ACCOUNT_DELETED"
},
"field": "account_update"
}
WhatsApp business account removed from partners
{
"value": {
"business_phone": "1669xxxx193",
"wabaId": "1049513xxxx7327",
"phone_number": "1669xxxx193",
"event": "PARTNER_REMOVED"
},
"field": "account_update"
}
A WhatsApp user resumes marketing messages.
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"contacts": [
{
"wa_id": "xxx"
}
],
"user_preferences": [
{
"wa_id": "xxx",
"detail": "User requested to resume marketing messages",
"category": "marketing_messages",
"value": "resume",
"timestamp": 1753865209
}
]
},
"field": "user_preferences"
}
A WhatsApp user stops marketing messages.
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "xxx",
"phone_number_id": "xxx"
},
"contacts": [
{
"wa_id": "xxx"
}
],
"user_preferences": [
{
"wa_id": "xxx",
"detail": "User requested to stop marketing messages",
"category": "marketing_messages",
"value": "stop",
"timestamp": 1753407219
}
]
},
"field": "user_preferences"
}
flows FLOW_STATUS_CHANGE
{
"field": "flows",
"value": {
"business_phone": "xxx",
"event": "FLOW_STATUS_CHANGE",
"flow_id": "xxx",
"message": "Flow zelin2 changed status from DRAFT to PUBLISHED",
"new_status": "PUBLISHED",
"old_status": "DRAFT",
"time": 1754040220,
"wabaId": "xxx"
}
}
flows ACTIVATED
{
"field": "flows",
"value": {
"alert_state": "ACTIVATED",
"business_phone": "xxx",
"event": "ENDPOINT_AVAILABILITY",
"flow_id": "xxx",
"message": "Flow endpoint availability was below 90% threshold in the last 60 minutes. Users are unable to open or use the flow.",
"threshold": 90,
"time": 1754335811,
"wabaId": "xxx"
}
}
flows DEACTIVATED
{
"field": "flows",
"value": {
"alert_state": "DEACTIVATED",
"business_phone": "xx",
"event": "ENDPOINT_AVAILABILITY",
"flow_id": "xxx",
"message": "Flow endpoint availability successfully recovered. Users will now be able to open and use the flow.",
"threshold": 90,
"time": 1754306033,
"wabaId": "xxx"
}
}