WhatsApp API webhook - nxtele/nxcloud-doc-en GitHub Wiki

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
  • conversation object parameters:
Parameter Name Type Description
id String Conversation ID
expiration_timestamp String Conversation expiration timestamp
origin JsonObject Conversation type information
  • 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"
  • error object parameters:
Parameter Name Type Description
code Integer Error code
meta_code Integer Meta Error code
title String Error message
  • cost object parameters:
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

{
    "statuses":[
        {
            "id":"wamid.HBgNODYxNzYwNjA1MDgxORUCABEYEjI4RTcyNzFGRDVGQTQwQkQ1RAA=",
            "status":"sent",
            "timestamp":"1660019986",
            "recipient_id":"86176xxxx0819",
            "conversation":{
                "id":"72569257438b471cae074da84bed1b83",
                "expiration_timestamp":"1660106400",
                "origin":{
                    "type":"authentication"
                }
            },
            "costs":[
                {
                    "currency":"USD",
                    "price":0,
                    "foreign_price":0,
                    "cdr_type":4,
                    "message_id":"wamid.HBgNNjI4MTI4MTM3NTYwNBUCABEYEkMzODdBNTEzMTAxNDhFMEI5NQA=",
                    "direction":1
                },
                {
                    "currency":"USD",
                    "price":0.1381,
                    "foreign_price":0.02,
                    "cdr_type":4,
                    "message_id":"wamid.HBgNNjI4MTI4MTM3NTYwNBUCABEYEkMzODdBNTEzMTAxNDhFMEI5NQA=",
                    "direction":1
                }
            ]
        }
    ]
}

Message Delivered

{
  "statuses": [
    {
      "id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABEYEjI4RTcyNzFGRDVGQTQwQkQ1RAA=",
      "status": "delivered",
      "timestamp": "1660019987",
      "recipient_id": "86176xxxx0819",
      "conversation": {
        "id": "72569257438b471cae074da84bed1b83",
        "origin": {
          "type": "authentication"
        }
      }
    }
  ]
}

Message Read

{
  "statuses": [
    {
      "id": "wamid.HBgNODYxNzYwNjA1MDgxORUCABEYEjI4RTcyNzFGRDVGQTQwQkQ1RAA=",
      "status": "read",
      "timestamp": "1660019990",
      "recipient_id": "86176xxxx0819"
    }
  ]
}

Message Failed

{
  "statuses": [
    {
      "errors": [
        {
          "code": 470,
          "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."
        }
      ],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
    }
  ]
}

Message Deleted

{
  "statuses": [
    {
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "deleted",
      "timestamp": "TIMESTAMP",
      "type": "message",
      "message": {
        "recipient_id": "WHATSAPP_ID"
      }
    }
  ]
}

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 
{
    "statuses": [
        {
            "id": "wamid.2e27ab39dbxxxxxxxb124a74b8",
            "errors": [
                {
                    "code": 9001,
                    "title": "System business error()"
                }
            ],
            "recipient_id": "3934xxxxx6000",
            "status": "failed",
            "timestamp": "1723604140"
        }
    ],
    "business_phone": "8523xxxxx862",
    "messaging_product": "whatsapp"
}

{
  "statuses": [
    {
      "errors": [
                {
                    "code": 10000,
                    "meta_code": 132001,
                    "title": "Meta Error((#132001) Template name does not exist in the translation)"
                }
            ],
      "id": "ID",
      "recipient_id": "WHATSAPP_ID",
      "status": "failed",
      "timestamp": "TIMESTAMP"
    }
  ]
}

{
	"statuses": [
		{
			"id": "wamid.302061d8f10d47fea6136ba290a2bda7",
			"errors": [
				{
					"code": 10000,
					"meta_code": 132005,
					"title": "Meta Error((#132005) Translated text too long)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1713504965"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.c14d12fc44d1439c92adf69b4e5a2a43",
			"errors": [
				{
					"code": 10000,
					"meta_code": 131009,
					"title": "Meta Error((#131009) Parameter value is not valid)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1713503819"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.456b7a1001754b0a8518517868071de8",
			"errors": [
				{
					"code": 10000,
					"meta_code": 100,
					"title": "Meta Error((#100) Invalid parameter)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1713500742"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.db8cc8d4a8bb4a969df274e25857cca5",
			"errors": [
				{
					"code": 10000,
					"meta_code": 131000,
					"title": "Meta Error((#131000) Something went wrong)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1713472479"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.3a9eefbbc792486da5850822dedcd8de",
			"errors": [
				{
					"code": 10000,
					"meta_code": 130429,
					"title": "Meta Error((#130429) Rate limit hit)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1713367837"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.f9f92a5a951749898060a257bd5668bb",
			"errors": [
				{
					"code": 10000,
					"meta_code": 132000,
					"title": "Meta Error((#132000) Number of parameters does not match the expected number of params)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1713426137"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.e8c6b1835fed401a8786ab1547ebf5af",
			"errors": [
				{
					"code": 10000,
					"meta_code": 10,
					"title": "Meta Error((#10) Application does not have permission for this action)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1712983756"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.d7cbc64872dc46ffabf76b8087d39933",
			"errors": [
				{
					"code": 10000,
					"meta_code": 131056,
					"title": "Meta Error((#131056) (Business Account, Consumer Account) pair rate limit hit)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1712912513"
		}
	]
}

{
	"statuses": [
		{
			"id": "wamid.d7cbc64872dc46ffabf76b8087d39933",
			"errors": [
				{
					"code": 10000,
					"meta_code": 131008,
					"title": "Meta Error((#131008) Parameter of type text is missing text value)"
				}
			],
			"recipient_id": "96650xxxx431",
			"status": "failed",
			"timestamp": "1712912513"
		}
	]
}


{
    "statuses": [
        {
            "id": "wamid.8caca9c7fxxxxxxxx2cd1a9a2111",
            "errors": [
                {
                    "code": 10001,
                    "title": "Wa Engine Error(获取meta message id 失败)"
                }
            ],
            "recipient_id": "386xxxx1268",
            "status": "failed",
            "timestamp": "1723500463"
        }
    ],
    "business_phone": "852664xxxx105",
    "messaging_product": "whatsapp"
}

{
    "statuses": [
        {
            "id": "wamid.807ff7e5026d4a4xxxx532a244232444",
            "errors": [
                {
                    "code": 10002,
                    "title": "Wa Engine Send Message Timeout"
                }
            ],
            "recipient_id": "417xxxx9752",
            "status": "failed",
            "timestamp": "1723337517"
        }
    ],
    "business_phone": "852xxxx3862",
    "messaging_product": "whatsapp"
}

Meta Webhook Failed

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "852xxxx3862",
        "phone_number_id": "161169xxxx19812"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgMMzkzNTA1OTYxxxxxxERgSMTJEQjQzNEYwRUEzNUI3ODY1AA==",
            "id": "wamid.4e03bc5bc12d4xxxxa51a9380c4bfb6",
            "recipient_id": "3935xxxx2976",
            "status": "failed",
            "timestamp": "1723337288",
            "errors": [
                {
                    "code": 131026,
                    "title": "Message Undeliverable."
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "852xxxx3862",
    "merchant_phone": "852xxxx3862",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "852xxxx3862",
        "phone_number_id": "161169xxxx19812"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgMOTY2NTU3ODk1OTIzxxxxxxxGRjFFNzNFRUE1N0YxRDQyAA==",
            "id": "wamid.eb78c85b970f4xxxxfdaba8a0f350128",
            "recipient_id": "9665xxxx5923",
            "status": "failed",
            "timestamp": "1723337111",
            "errors": [
                {
                    "code": 131053,
                    "title": "Unsupported Image mime type image/webp. Please use one of image/png, image/jpeg."
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "852xxxx3862",
    "merchant_phone": "852xxxx3862",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "852xxxx3313",
        "phone_number_id": "24094xxxx439281"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgLODUyNTQxxxxxxxxI5MTkwRkIzQTlBMEY3RDQ0NjYA",
            "id": "wamid.30bf536d5ad6xxxxxxe144dcf31",
            "recipient_id": "852xxxxx409",
            "status": "failed",
            "timestamp": "1723345890",
            "errors": [
                {
                    "code": 130472,
                    "title": "Failed to send message because this user's phone number is part of an experiment",
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "852xxxxx313",
    "merchant_phone": "852xxxxx313",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "6221xxxx0365",
        "phone_number_id": "10652xxxx19185"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgNNjI4NTIzNjg5ODAzNhUCABIYIDxxxxxxxxxxxxxxxxxxxTJFNEVFNDIyNDJCRDE4MzUzAA==",
            "id": "wamid.HBgNNjI4NTIzNjg5ODAzNhUCABIYIDxxxxxxxxxxxxxxxxxxxTJFNEVFNDIyNDJCRDE4MzUzAA==",
            "recipient_id": "62852xxxx8036",
            "status": "failed",
            "timestamp": "1723370701",
            "errors": [
                {
                    "code": 131052,
                    "title": "Incoming media file validation failed or the received media is in incorrect format, please ask the sender to resend the media message."
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "62852xxxx8036",
    "merchant_phone": "62852xxxx8036",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "62852xxxx8036",
        "phone_number_id": "271352389392750"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgKNTkyNjIxMzcxMRsxxxxxxxxFNkI5MkVDMDlCMUY5OTE1QgA=",
            "id": "wamid.870f44e7a4xxxxxxxx4a7763938e7009",
            "recipient_id": "5926213711",
            "status": "failed",
            "timestamp": "1723441066",
            "errors": [
                {
                    "code": 131009,
                    "title": "Cannot react to a message if it's more than 30 days old or doesn't correspond to any message in the conversation."
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "62852xxxx8036",
    "merchant_phone": "62852xxxx8036",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "62852xxxx8036",
        "phone_number_id": "10347xxxx349406"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgNNDkxNTIwNjYxMDI5MhUCABEYEkFGNzUwMDExNDAyQUQ0OUY4QwA=",
            "id": "wamid.db05dcfd6a5347ac9d97c27e5e7ab68d",
            "recipient_id": "4915206610292",
            "status": "failed",
            "timestamp": "1723444780",
            "errors": [
                {
                    "code": 131047,
                    "title": "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/"
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "62852xxxx8036",
    "merchant_phone": "62852xxxx8036",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "62852xxxx8036",
        "phone_number_id": "268080186388284"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgMOTcxNTAzMTEwOxxxxxxxxx0ODJEN0ZFRUU4AA==",
            "id": "wamid.e5fee94051bf4929xxxx31beb6821",
            "recipient_id": "971503110900",
            "status": "failed",
            "timestamp": "1723464255",
            "errors": [
                {
                    "code": 131000,
                    "title": "Something went wrong."
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "62852xxxx8036",
    "merchant_phone": "62852xxxx8036",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "852664xxxx105",
        "phone_number_id": "277xxxxxxxxx8733"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgNNjI4MjI3Nzg4OTU5ORUCxxxxxxxxxM3QzlERDUxQjNBQQA=",
            "id": "wamid.f40485e53bd1xxxxxxxxxc669c3a",
            "recipient_id": "6282xxxxxxx9599",
            "status": "failed",
            "timestamp": "1723616606",
            "errors": [
                {
                    "code": 131031,
                    "title": "Business account has been locked.",
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "852664xxxx105",
    "merchant_phone": "852664xxxx105",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "852664xxxx105",
        "phone_number_id": "17205xxxxx1593"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgLMzM3NjIxNjxxxxxxxxxxxxxjg4RUQyRUFBNjFFOTUA",
            "id": "wamid.61e1f287fxxxxxxx1e37e75adaa6",
            "recipient_id": "337xxxxx383",
            "status": "failed",
            "timestamp": "1723639940",
            "errors": [
                {
                    "code": 131048,
                    "title": "Message failed to send because there are restrictions on how many messages can be sent from this phone number.This may be because too many previous messages were blocked or flagged as spam.",
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
                }
            ]
        }
    ],
    "app_id": "xxx",
    "business_phone": "852664xxxx105",
    "merchant_phone": "852664xxxx105",
    "channel": 2
}

{
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "852664xxxx105",
        "phone_number_id": "17205xxxxx1593"
    },
    "statuses": [
        {
            "meta_message_id": "wamid.HBgNNTIxODQ0NjEwODU2ORUCABEYExxxxxxFOERBRjlERDg4NkU4QwA=",
            "id": "24a44ec9155145b9xxxxxx28b148b11",
            "recipient_id": "521xxxxxx8569",
            "status": "failed",
            "timestamp": "1726630150",
            "errors": [
                {
                    "code": 131049,
                    "title": "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/"
                }
            ]
        }
    ],
    "app_id": "749",
    "business_phone": "852664xxxx105",
    "merchant_phone": "852664xxxx105",
    "channel": 2
}

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
  • cost object parameters:
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)
  • Message Types
  1. Text Message Parameters:
Parameter Name Type Description
text JsonObject Refer to response example Text message content, available when type=text
  • text object parameters:
Parameter Name Type Description
body String Message text
  1. Image Message Parameters:
Parameter Name Type Description
image JsonObject Refer to response example Image message content, available when type=image
  • image object 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
  1. Video Message Parameters:
Parameter Name Type Description
video JsonObject Refer to response example Video message content, available when type=video
  • video object 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
  1. Voice Message Parameters:
Parameter Name Type Description
voice JsonObject Refer to response example Voice message content, available when type=voice
  • voice 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
  1. Audio Message Parameters:
Parameter Name Type Description
audio JsonObject Refer to response example Audio message content, available when type=audio
  • audio 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
  1. 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
  1. 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
  1. 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
  1. Interactive Message Parameters:
Parameter Name Type Description
interactive JsonObject Refer to response example 1Refer to response example 2There is a value when type=interactive
  • 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)
  1. Order Message Parameters:
Parameter Name Type Description
order JsonObject Refer to response example There is a value when type=order
  • order object 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 |

  1. referral Message Parameters:
Parameter Name Type Description
context JsonObject Product message response example Quote message response example Only exists when the user replies to or interacts with one of your messages
  • 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
  1. 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
  1. 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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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

```json
{
	"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"
}