> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp 入站消息 Webhook 示例
> 通过带有注释的有效负载示例处理入站 WhatsApp 消息类型。
有关基于架构派生的完整目录，请参阅[所有示例](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。
## 功能介绍
通过带有注释的有效负载示例处理入站 WhatsApp 消息类型。
## 准备工作
* 在您的应用程序中创建一个公开的 HTTPS 端点。
* 为您需要的事件类型配置 YCloud Webhook 端点。
* 安全存储端点签名密钥。
* 确保事件处理具有幂等性。
## 工作原理
事件发生时，YCloud 会发送 HTTP `POST` 请求。验证签名，持久化记录事件，返回 `2xx` 响应，并异步处理耗时任务。
## 请求
以下场景展示了传递到您的 Webhook URL 的请求。将事件 `id` 视为传递标识符，并使用 `type` 路由有效负载。
## 响应
接收事件后返回 `2xx` 状态。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
有关端点设置、签名验证和重试机制，请参阅[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。
## 入站不支持的消息
在此情况下，您的 Webhook 端点收到了入站不支持的消息：
* `type` 设置为 `unsupported`。
* `errors` 说明了该消息不受支持或不可用的原因。
* `unsupported.type` 标识消息类别，例如 `poll_creation`、`poll_update`、`edit` 或 `pin`。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f8709b741c165b4342a714",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"errors": [
{
"code": 131051,
"title": "Message type unknown",
"message": "Message type unknown",
"error_data": {
"details": "Message type is currently not supported."
}
}
],
"type": "unsupported",
"unsupported": {
"type": "poll_update"
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 错误 `131051` 及 `Message type unknown` 表示 WhatsApp Cloud API 不支持该消息类型。
* 错误 `131060` 及 `This message is currently unavailable.` 表示 WhatsApp 无法提供消息内容。
* `unsupported.type` 标识通用类别。它不包含原始消息内容。
* 有关消息类型的可读列表，请参阅[收件箱中不支持的消息](/zh/documentation/inbox/unsupported-messages-in-inbox)。有关当前的有效负载约定，请参阅 Meta 的[不支持的消息 Webhook 参考](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/unsupported)。
## 入站文本消息
在此情况下，您的 Webhook 端点收到了入站文本消息：
* 包含用户发送的纯文本。
* 在 `context` 中包含所提及消息的信息。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eEkn26qar3nOB8md",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f872f6741c165b4342a751",
"wamid": "wamid.HBgNODi...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "text",
"text": {
"body": "OK"
},
"context": {
"from": "447901614024",
"id": "wamid.HBgNODr..."
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* **入站消息是客户发送到您的商业电话号码的消息。**
* `context`（可选）包含所提及消息的信息，通常用于回复用户或您的企业之前发送的消息。
* `context.from` 是发送所提及消息的用户的 WhatsApp ID（不带“+”前缀的电话号码）。
* `context.id` 是所提及消息在 WhatsApp 平台上的原始 ID，以 `wamid.` 开头。
## 通过点击 WhatsApp 广告触发的入站文本消息
在此情况下，您的 Webhook 端点收到了通过点击 WhatsApp 广告触发的入站文本消息：
* 包含纯文本。
* 包含有关广告的信息。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eEkn26qar3nOB8md",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f872f6741c165b4342a751",
"wamid": "wamid.HBgNODi...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "text",
"text": {
"body": "OK"
},
"referral": {
"source_url": "https://fb.me/xxx",
"source_type": "ad",
"source_id": "MEDIA-ID",
"headline": "Chat with us",
"media_type": "image",
"image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg",
"ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd"
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* `referral` 包含有关广告的信息。另请参阅 [Click to WhatsApp 广告](https://www.facebook.com/business/help/447934475640650)。
## 入站图片消息
在此情况下，您的 Webhook 端点收到了入站图片消息：
* 包含图片 URL。
* 包含描述该图片的说明文字。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eEkv5wsCJItpaH01",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f87878509703399f3fd3d0",
"wamid": "wamid.HBgNODi...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "image",
"image": {
"link": "https://api.ycloud.com/v2/whatsapp/media/download/592623615738103?sig=t%3D1677228150%2Cs%3D0aa4810392602afb2a91e28e54223c4c0e638bba298f19f07a6c3a2ccf6bdf1e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc4Nzg1MDk3MDMzOTlmM2ZkM2QwIiwibWltZVR5cGUiOiJpbWFnZS9qcGVnIiwic2hhMjU2IjoiTGVScFFKcS9oNEhUam1QOHNtRkpRRXdZQm5rR0JVdDFjeDRxekZjblVoUT0ifQ",
"caption": "Go for a walk.",
"id": "592623615738103",
"sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
"mime_type": "image/jpeg"
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 为了方便使用者，`image.link` 可以在几分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在 30 天内下载此文件。
## 入站视频消息
在此情况下，您的 Webhook 端点收到了入站视频消息：
* 包含视频 URL。
* 包含描述该视频的说明文字。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eEkwhYtqMPmYdsN3",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f87991741c165b4342a797",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "video",
"video": {
"link": "https://api.ycloud.com/v2/whatsapp/media/download/919306472440541?sig=t%3D1677228430%2Cs%3D481b972ebc10e6b384f11274ba59e64b8c355543ea0b30e066b209361212abad&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc5OTE3NDFjMTY1YjQzNDJhNzk3IiwibWltZVR5cGUiOiJ2aWRlby9tcDQiLCJzaGEyNTYiOiJ4RHpyU1R1YnZURm53MytzMVdJbEFiSUZLanpBS2k1dFZWaVFOVjhKV3BnPSJ9",
"caption": "Go for a walk.",
"id": "919306472440541",
"sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
"mime_type": "video/mp4"
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 为了方便使用者，`video.link` 可以在几分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在 30 天内下载此文件。
## 入站音频消息
在此情况下，您的 Webhook 端点收到了入站音频消息：
* 包含音频 URL。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eEl1TDAcquZUxzLn",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f87cd3509703399f3fd3f2",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "audio",
"audio": {
"link": "https://api.ycloud.com/v2/whatsapp/media/download/712063723747110?sig=t%3D1677229265%2Cs%3D5c6a65172ef8caa7bc969dacb831d6e15362fd7a5b6be7aa994aa83cdd15fc4e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdjZDM1MDk3MDMzOTlmM2ZkM2YyIiwibWltZVR5cGUiOiJhdWRpby9tcGVnIiwic2hhMjU2IjoiQWtSWkR5dEx5MkkxSzFkT2VMNnBRT2pZblBwcGdqdFNDTzlNUStDcnkwUT0ifQ",
"id": "712063723747110",
"sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
"mime_type": "audio/mpeg"
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 为了方便使用者，`audio.link` 可以在几分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在 30 天内下载此文件。
## 入站文档消息
在此情况下，您的 Webhook 端点收到了入站文档消息：
* 包含文档 URL。
* 包含描述该文档的说明文字。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eEkz3y7V6TCqgkbK",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f87b2e741c165b4342a79b",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "document",
"document": {
"link": "https://api.ycloud.com/v2/whatsapp/media/download/948915536111569?sig=t%3D1677228843%2Cs%3D6eb8b4fc2796bae9f2e95702fbbd4d211cace96bc5c934a12d97704140e47a16&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdiMmU3NDFjMTY1YjQzNDJhNzliIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYiLCJzaGEyNTYiOiJFcHZDdHpUallkcTRleG1xc2ZHYmVpK1NUZ1h4VnFUQzJ0b2laODB2bW5rPSJ9",
"caption": "PDF example",
"filename": "sample.pdf",
"id": "948915536111569",
"sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
"mime_type": "application/pdf"
}
}
}'
```
### 响应
持久化接收事件后确认交付。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 为了方便使用者，`document.link` 可以在几分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在 30 天内下载此文件。
## 入站贴纸消息
在此情况下，您的 Webhook 端点收到了入站贴纸消息：
* 包含贴纸 URL。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63fc1678741c165b4342b38e",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "sticker",
"sticker": {
"link": "https://api.ycloud.com/v2/whatsapp/media/download/729118992174848?sig=t%3D1677465205%2Cs%3Dbc0d582e37cc701d5d090c1d11aa7eaed9b3f8e83925425a82d0aaab8b7da258&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmYzE2Nzg3NDFjMTY1YjQzNDJiMzhlIiwibWltZVR5cGUiOiJpbWFnZS93ZWJwIiwic2hhMjU2IjoiUlpFRWw1SFZXVDRTNkMwUG9PZ2pZQ1FWRFdzNWVzSU1Kc2pjRFlJODBaRT0ifQ",
"id": "729118992174848",
"sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
"mime_type": "image/webp"
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 为了方便使用者，`sticker.link` 可以在几分钟内直接访问，但您应始终包含 `X-API-Key` 请求头以便在 30 天内下载此文件。
## 入站位置消息
在此情况下，您的 Webhook 端点收到了入站位置消息：
* 包含地点的纬度和经度。
* 包含地点的名称、地址和 URL。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63fc18ae509703399f3fe000",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "location",
"location": {
"latitude": 1.40435,
"longitude": 103.79304,
"name": "Singapore Zoo",
"address": "80 Mandai Lake Road Singapore 72",
"url": "https://www.zoo.com.sg"
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
按 `type` 路由事件，按 `id` 进行去重，并将耗时或易失败的工作转移至异步处理器。
## 入站联系人消息
在此情况下，您的 Webhook 端点收到了入站联系人消息：
* 包含一个联系人信息，包含地址、生日、电子邮件、姓名、电话及其他联系人字段。
* 当用户响应索取联系信息消息而分享联系人时，包含 `origin: contact_request`。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "contacts",
"contacts": [
{
"addresses": [
{
"street": "",
"city": "",
"state": "",
"zip": "",
"country": "",
"country_code": "",
"type": "HOME"
}
],
"birthday": "2001-01-01",
"emails": [
{
"email": "joe@example.com",
"type": "WORK"
}
],
"name": {
"formatted_name": "",
"first_name": "",
"last_name": "",
"middle_name": "",
"suffix": "",
"prefix": ""
},
"org": {
"company": "",
"department": "",
"title": ""
},
"phones": [
{
"phone": "+447901614024",
"wa_id": "447901614024",
"type": "WORK"
}
],
"origin": "contact_request",
"urls": [
{
"url": "",
"type": "WORK"
}
]
}
]
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
按 `type` 路由事件，按 `id` 进行去重，并将耗时或易失败的工作转移至异步处理器。
## 入站 Reaction 消息
在此情况下，您的 Webhook 端点收到了入站 Reaction 消息：
* 包含用户做出反应的消息 ID。
* 包含 emoji 表情。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "reaction",
"reaction": {
"message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
"emoji": "👍"
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 当用户使用 emoji 对消息作出反应时，存在 `emoji`。如果不存在，则表示用户移除了对消息的 emoji 反应。
## 入站模板按钮消息
在此情况下，您的 Webhook 端点收到了入站模板按钮消息：
* 包含您在发送模板消息时所使用模板的按钮 `text`。
* 包含您在发送模板消息时提供的按钮 `payload`。
* 包含您发送的模板消息的 wamid（`context.wamid`）。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "button",
"button": {
"payload": "more_about_marketing_friday",
"text": "Learn more"
},
"context": {
"from": "447901614024",
"id": "wamid.HBgNODr..."
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
按 `type` 路由事件，按 `id` 进行去重，并将耗时或易失败的工作转移至异步处理器。
## 入站交互式列表回复消息
在此情况下，您的 Webhook 端点收到了入站交互式列表回复消息：
* `interactive` 字段包含用户在您之前发送的交互式消息中点击的列表回复。
* `context` 字段包含关于您之前发送给用户的交互式消息的信息。
 点击按钮选择一个项目。
 收件人通过选择您之前发送的交互式消息中的一个项目来回复您的消息。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f73942741c165b43429f86",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "",
"title": "",
"description": ""
}
},
"context": {
"from": "447901614024",
"id": "wamid.HBgNODr..."
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* `context` 包含关于您之前发送的交互式消息的信息。
* `context.from` 是发送该交互式消息的用户 WhatsApp ID（不带“+”前缀的电话号码）。
* `context.id` 是 WhatsApp 平台上的原始消息 ID，以 `wamid.` 开头。
## 入站交互式按钮回复消息
在此情况下，您的 Webhook 端点收到了入站交互式按钮回复消息：
* `interactive` 字段包含用户在您之前发送的交互式消息中点击的按钮回复。
* `context` 字段包含关于您之前发送给用户的交互式消息的信息。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "",
"title": ""
}
},
"context": {
"from": "447901614024",
"id": "wamid.HBgNODr..."
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* `context` 包含关于您之前发送的交互式消息的信息。
* `context.from` 是发送该交互式消息的用户 WhatsApp ID（不带“+”前缀的电话号码）。
* `context.id` 是 WhatsApp 平台上的原始消息 ID，以 `wamid.` 开头。
## 入站交互式 Flow 响应消息
Flow 完成后，系统将向 WhatsApp 聊天发送一条响应消息。您将像接收来自用户的所有其他消息一样接收它——通过消息 Webhook。`response_json` 字段将包含 Flow 专属数据。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "interactive",
"interactive": {
"type": "nfm_reply",
"nfm_reply": {
"name": "flow",
"body": "Sent",
"response_json": "{\"flow_token\": \"\", \"optional_param1\": \"\", \"optional_param2\": \"\"}"
}
},
"context": {
"from": "447901614024",
"id": "wamid.HBgNODr..."
}
}
}'
```
### 响应
在持久化接收事件后确认投递。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* `interactive.type` 始终为 `nfm_reply`。`interactive.name` 始终为 `flow`。`interactive.body` 始终为 `Sent`。
* `interactive.response_json` 为 Flow 专属数据。其结构要么在 Flow JSON 中定义（参见 [Complete action](https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson#complete-action)），要么（如果 Flow 使用了端点）由端点控制（参见 [Data Exchange Request](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint#data_exchange_request) 中的 Final Response Payload）。将 `interactive.response_json` JSON 字符串解析为 JSON 对象，其值的数据类型可以多样。通常值是纯文本，以下情况除外：
* 当它源自 [CheckboxGroup](https://developers.facebook.com/docs/whatsapp/flows/reference/components#checkbox) 组件时，该值为字符串列表。
* 当它来源于 [OptIn](https://developers.facebook.com/docs/whatsapp/flows/reference/components#opt) 组件时，该值为布尔值，即 `true` 或 `false`。目前，如果存在该键，其值必须为 `true`，因为如果用户未选择加入（opt in），`response_json` 中将不会包含此类键。
* 当它来源于 [DatePicker](https://developers.facebook.com/docs/whatsapp/flows/reference/components#dp) 组件时，该值为表示毫秒级 Unix 时间戳的字符串，例如 `"1725936737548"`（即 2024-09-10T02:52:17.548Z）。从 [Flow JSON 版本 5.0](https://developers.facebook.com/docs/whatsapp/flows/changelogs#august-13th--2024-release) 开始，日期将设置为 "yyyy-MM-dd" 格式，这使得其值与时区无关。
* 如需使用 Flow 发送消息，请参阅 [Flow 消息模板](/zh/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#flow-template-message) 以及 [交互式 Flow 消息](/zh/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#interactive-flow-message)。
## 入站系统消息
在此情况下，您的 Webhook 端点收到了一条入站系统消息：
* `type` 设置为 `system`，且 `system.type` 设置为 `user_changed_number`。
* 用户在 WhatsApp 上更改了其电话号码，`wa_id` 是新的 WhatsApp ID（不带 `+` 前缀的电话号码）。
* `user_id` 是新的 BSUID。仅当启用了父级 BSUID 时才会包含 `parent_user_id`。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "system",
"system": {
"body": "User A changed from 123456789 to 987654321",
"wa_id": "987654321",
"user_id": "US.13491208655302741919",
"parent_user_id": "US.ENT.11815799212886844831",
"type": "user_changed_number"
}
}
}'
```
### 响应
在持久化接收事件后确认送达。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
按 `type` 路由事件，按 `id` 去重，并将耗时或易出错的操作移至异步处理器。
## 入站订单消息
在此情况下，当客户将一件或多件商品加入购物车并提交订单时，您的 Webhook 端点收到了一条入站订单消息：
* 包含已订购商品的信息。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "order",
"order": {
"catalog_id": "the-catalog_id",
"product_items": [
{
"product_retailer_id": "the-product-SKU-identifier",
"quantity": "number-of-item",
"item_price": "unitary-price-of-item",
"currency": "price-currency"
}
],
"text": "text-message-sent-along-with-the-order"
},
"context": {
"from": "16315551234",
"id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}
}
}'
```
### 响应
在持久化接收事件后确认送达。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
按 `type` 路由事件，按 `id` 去重，并将耗时或易出错的操作移至异步处理器。
## 入站商品咨询消息
在此情况下，当客户咨询商品时，您的 Webhook 端点收到了一条入站文本消息：
* 包含商品信息。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "text",
"text": {
"body": "Can I get this in another color?"
},
"context": {
"referred_product": {
"catalog_id": "catalog-ID",
"product_retailer_id": "product-ID"
}
}
}
}'
```
### 响应
在持久化接收事件后确认送达。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 当用户咨询特定商品的更多信息时，将收到商品咨询消息（Product Inquiry Message）。该消息可能在以下两种情况下收到：
* 客户回复 [单商品或多商品消息](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services/share-products) 时。
* 客户通过其他入口访问商家的商品目录，进入商品详情页面，并点击“向商家发送关于此商品的消息”时。
## 入站请求欢迎消息
每当 WhatsApp 用户首次与您开启对话时，您都可以通过 Webhook 收到通知。如果您希望使用自定义设计的欢迎消息回复这些用户，这会非常有用。
如果您启用了此功能并且用户打开了对话（通常是用户点击了[通用链接](https://faq.whatsapp.com/425247423114725)，例如 **wa.me** 或 **api.whatsapp.com** 链接），WhatsApp 客户端会检查该用户与您的商业电话号码之间是否存在既有的消息对话。如果不存在，客户端将触发 `request_welcome` Webhook。随后您可以使用自己的欢迎消息回复该用户。
### 请求
```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
"id": "evt_eF6mVJUj5OWfKXMD",
"type": "whatsapp.inbound_message.received",
"apiVersion": "v2",
"createTime": "2023-02-22T12:00:00.000Z",
"whatsappInboundMessage": {
"id": "63f71fb8741c165b434292fb",
"wamid": "wamid.HBgNOD...",
"wabaId": "WABA-ID",
"from": "CUSTOMER-PHONE-NUMBER",
"fromUserId" : "US.13491208655302741918",
"fromParentUserId": "US.ENT.11815799212886844830",
"customerProfile": {
"name": "Joe",
"username": "@JoeJoe"
},
"to": "BUSINESS-PHONE-NUMBER",
"sendTime": "2023-02-22T12:00:00.000Z",
"type": "request_welcome"
}
}'
```
### 响应
在持久化接收事件后确认送达。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
* 如需为某个电话号码启用此功能，请前往 Meta **WhatsApp 管理工具** > **电话号码** > **设置** > **自动化**。
* 若要测试 `request_welcome` 消息，如果您已经与该商业电话号码存在正在进行的对话，必须先删除该聊天。
* 此功能仅会触发入站 `request_welcome` 消息，不会自动回复任何消息。是否回复欢迎消息完全由您决定。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.