新消息回调
回调地址
回调请求方式
回调内容
参数说明
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
回调事件名称，这里为 "new_message" |
| business_phone |
string |
是 |
whatsapp business phone number |
| message |
object |
是 |
WhatsApp 消息内容，不同的消息内容会有所差别 |
message Object
| Name |
Description |
contactsarray of objects |
Array of contact objects with information for the customer who sent a message to the business. Contact objects have the following properties:
wa_id — String. The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as input when sending a message to the customer.profile — Object. A customer profile object. Profile objects have the following properties:
name — String. The customer's name.
|
errorsarray of objects |
An array of error objects describing the error. Error objects have the following properties, which map to their equivalent properties in API error response payloads.
- Webhooks triggered by v15.0 and older requests:
code — Integer. Example: 130429.title — String. Error code title. Example: Rate limit hit.
- Webhooks triggered by v16.0 and newer requests:
code — Integer. Error code. Example: 130429.title — String. Error code title. Example: Rate limit hit.message — String. Error code message. This value is the same as the title value. For example: Rate limit hit. Note that the message property in API error response payloads pre-pends this value with the a # symbol and the error code in parenthesis. For example: (#130429) Rate limit hit.error_data — Object. An error data object with the following properties:
details — String. Describes the error. Example: Message failed to send because there were too many messages sent from this phone number in a short period of time.
|
messaging_productstring |
Product used to send the message. Value is always whatsapp. |
messagesarray of objects |
Information about a message received by the business that is subscribed to the webhook. See Messages Object. |
metadataobject |
A metadata object describing the business subscribed to the webhook. Metadata objects have the following properties:
display_phone_number — String. The phone number that is displayed for a business.phone_number_id — String. ID for the phone number. A business can respond to a message using this ID.
|
statusesarray of objects |
Status object for a message that was sent by the business that is subscribed to the webhook. See Statuses Object. |
Messages Objects
| Name |
Description |
audioobject |
When the messages type is set to audio, including voice messages, this object is included in the messages object:
id — String. ID for the audio file.mime_type — String. Mime type of the audio file.
|
buttonobject |
When the messages type field is set to button, this object is included in the messages object:
payload – String. The payload for a button set up by the business that a customer clicked as part of an interactive message.text — String. Button text.
|
typestring |
The type of message that has been received by the business that has subscribed to Webhooks. Possible value can be one of the following: audiobuttondocumenttextimageinteractiveorderstickersystem – for customer number change messagesunknownvideo |
videoobject |
When messages type is set to video, this object is included in messages object. Video objects have the following properties:
caption – String. The caption for the video, if provided.sha256 – String. The hash for the video.id – String. The ID for the video.mime_type – String. The mime type for the video file.
|
#### 回调示例
##### text 纯文本
```json
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [ // 发信人信息
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUY1Qjc4MUQzNjM3OTk1QUVENQA=",
"timestamp": "1756109460",
"text": {
"body": "hello"
},
"type": "text"
}
]
}
}
```
##### reaction 引用回复
```json
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"context": { // 引用的消息
"from": "6281519236680",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBI5RkEyNjU2NEUwMDhBRDMxNTEA"
},
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTY5OUZERjU5MDZBQzUyN0Y0MgA=",
"timestamp": "1756113398",
"text": {
"body": "OK"
},
"type": "text"
}
]
}
}
```
##### image 图片
```json
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUZCMzlCREIwMDdCMkYzRjZBQgA=",
"timestamp": "1756111162",
"type": "image",
"image": {
"mime_type": "image\/jpeg",
"sha256": "X+rJ8sVYdTYG9nD3JOGjJAb4GE3qw89S8kQNQ2fRj1w=",
"id": "2173590463051074",
"link": "https:\/\/static.incsapp.com\/chat\/images\/2173590463051074.jpg"
}
}
]
}
}
```
sticker 贴纸
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUM4MzBCOUIzNTk4RTI1MUE5OQA=",
"timestamp": "1756111078",
"type": "sticker",
"sticker": {
"mime_type": "image\/webp",
"sha256": "1RgjeZcCQQjyzYnvcvInvzes\/n9ThHJ4Ndr3dzGUeP0=",
"id": "782472500814983",
"animated": false,
"link": "https:\/\/static.incsapp.com\/chat\/images\/782472500814983.webp"
}
}
]
}
}
video 视频
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTA3Qzg2MTAyQTgxRDBCQkQ0RgA=",
"timestamp": "1756111347",
"type": "video",
"video": {
"caption": "beautiful\uff1f", // 用户添加的描述
"mime_type": "video\/mp4",
"sha256": "8m71YIxOHqc3HYGthZiquLeeE0N1Cv0MeTc25ahf4sU=",
"id": "1277927410543839",
"link": "https:\/\/static.incsapp.com\/chat\/videos\/1277927410543839.mp4"
}
}
]
}
}
audio 语音
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUFBQzc3RUVCQTRCNDMxOTNBMgA=",
"timestamp": "1756112512",
"type": "audio",
"audio": {
"mime_type": "audio\/ogg; codecs=opus",
"sha256": "pp0SvItSzmvP6mRp1mR\/4tn9ydbnv72YWiZ9XxaxTZg=",
"id": "1082985930630339",
"voice": true,
"link": "https:\/\/static.incsapp.com\/chat\/audios\/1082985930630339.ogg"
}
}
]
}
}
document 文档
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTg3MUUyRjA4RDA3RTdFQzUyNwA=",
"timestamp": "1756112790",
"type": "document",
"document": {
"filename": "email_template_en.xls",
"mime_type": "application\/vnd.ms-excel",
"sha256": "0WWrm0sDQYStNhqArO7uRiViw40SbSP+QALrNGyi4pE=",
"id": "797337589311657",
"link": "https:\/\/static.incsapp.com\/chat\/files\/797337589311657.xls"
}
}
]
}
}
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTdCQzYyMEM0NjcxQkYzN0VFOQA=",
"timestamp": "1756112662",
"type": "contacts",
"contacts": [
{
"name": {
"first_name": "Lessie Laytoya",
"formatted_name": "Lessie Laytoya"
},
"phones": [
{
"phone": "+85268415026",
"wa_id": "85268415026",
"type": "CELL"
}
]
}
]
}
]
}
}
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"context": { // 选项关联的某条消息
"from": "6281519236680",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBJGNDY4NjdEN0I3QkZCMzg5QjMA"
},
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUM5MzJGN0EwRThCNTgyRTVFNAA=",
"timestamp": "1756112962",
"type": "button",
"button": {
"payload": "\u8fd8\u6709\u5176\u4ed6\u95ee\u9898",
"text": "\u8fd8\u6709\u5176\u4ed6\u95ee\u9898"
}
}
]
}
}
location 位置
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTczMTRCMzNDNjgwMzExNkUyNgA=",
"timestamp": "1756113235",
"location": {
"latitude": 22.570337295532,
"longitude": 113.87411499023,
"name": "\u534e\u4e30\u91d1\u878d\u6e2f" // 选填
},
"type": "location"
}
]
}
}
order 订单
- A WhatsApp user orders one or more products via a catalog, single-, or multi-product message.
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Sheena Nelson"
},
"wa_id": "16505551234"
}
],
"messages": [
{
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"timestamp": "1750096325",
"type": "order",
"order": {
"catalog_id": "194836987003835",
"text": "Love these!",
"product_items": [
{
"product_retailer_id": "di9ozbzfi4",
"quantity": 2,
"item_price": 30,
"currency": "USD"
},
{
"product_retailer_id": "nqryix03ez",
"quantity": 1,
"item_price": 25,
"currency": "USD"
}
]
}
}
]
}
}
Interactive 交互式消息
- A WhatsApp user taps a row in an interactive list message.
- A WhatsApp user taps a button in an interactive reply button message.
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Sheena Nelson"
},
"wa_id": "16505551234"
}
],
"messages": [
{
"context": {
"from": "15550783881",
"id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA="
},
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"timestamp": "1749854575",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "priority_express",
"title": "Priority Mail Express",
"description": "Next Day to 2 Days"
}
}
}
]
}
}
Unsupported 不支持的消息类型
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUQ1NzI3MTZFMDlBNEE0RkU4RQA=",
"timestamp": "1756113604",
"errors": [
{
"code": 131051,
"title": "Message type unknown",
"message": "Message type unknown",
"error_data": {
"details": "Message type is currently not supported."
}
}
],
"type": "unsupported"
}
]
}
}
