> ## 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.inbound_message.received > 在收到 WhatsApp 入站消息时触发。 使用 `whatsapp.inbound_message.received` 在您的 Webhook 端点处理此事件。 ## 触发条件 在收到 WhatsApp 入站消息时触发。 在您[配置 Webhook 端点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)时订阅 `whatsapp.inbound_message.received`。 使用消息 `type` 来选择其内容对象。媒体、交互式回复、位置、联系人和系统通知具有不同的字段。以下示例展示了这些变体。 ## 语法 YCloud 会向您配置的 Webhook URL 发送一个 HTTP `POST` 请求。以下结构展示了一种负载变体。尖括号中的值为占位符；其类型列在 **参数** 下。可选字段和其他变体在下方说明。 ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "", "type": "whatsapp.inbound_message.received", "apiVersion": "", "createTime": "", "whatsappInboundMessage": { "id": "", "wamid": "", "wabaId": "", "to": "", "sendTime": "", "type": "", "system": { "type": "", "previous_user_id": "", "previous_parent_user_id": "" } } } ``` ## 参数 在处理 JSON 请求体之前，请验证 `YCloud-Signature` HTTP 请求头。请参阅[签名验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。 ### 事件外层结构 | 参数 | 类型 | 是否必填 | 说明 | | - | - | - | - | | `id` | string | 是 | 事件的唯一 ID。最小长度：`6`。最大长度：`128`。 | | `type` | string | 是 | 固定为 `whatsapp.inbound_message.received`。 | | `apiVersion` | string | 是 | 用于呈现此事件的 API 版本。 | | `createTime` | string (date-time) | 是 | 此事件的创建时间，格式为 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)。例如：`2022-06-01T12:00:00.000Z`。 | ### 事件负载 | 参数 | 类型 | 是否必填 | 说明 | | - | - | - | - | | `whatsappInboundMessage` | object | 否 | 特定事件的 `whatsappInboundMessage` 负载。 | 外层结构的四个通用字段是必填的。负载字段取决于具体的事件变体。在各个对象表格中，当其父对象存在时， **是否必填** 规则生效。可选字段可以省略；示例中包含某字段并不意味着该字段是必填的。 #### whatsappInboundMessage | 参数 | 类型 | 是否必填 | 说明 | | - | - | - | - | | `id` | string | 是 | 对象的唯一 ID。 | | `wamid` | string | 否 | WhatsApp 平台上的原始消息 ID。 | | `wabaId` | string | 否 | WhatsApp 商业账户 ID。 | | `from` | string | 否 | 向企业发送消息的客户电话号码，格式为 [E.164](https://en.wikipedia.org/wiki/E.164) 格式。 | | `fromUserId` | string | 否 | 客户的 WhatsApp 商业范围用户 ID（BSUID）。 | | `fromParentUserId` | string | 否 | 客户的父级 WhatsApp 商业范围用户 ID。 | | `customerProfile` | object | 否 | 客户的个人资料信息。 | | `to` | string | 否 | 接收者的电话号码，采用 [E.164](https://en.wikipedia.org/wiki/E.164) 格式。 | | `sendTime` | string (date-time) | 否 | 发送此消息的时间，格式为 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)。例如：`2022-06-01T12:00:00.000Z`。 | | `type` | string | 否 | WhatsApp 入站消息类型。另请参阅 [WhatsApp webhook messages object](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#messages-object)。取值：`text`、`image`、`video`、`audio`、`document`、`sticker`、`contacts`、`location`、`interactive`、`button`、`reaction`、`request_welcome`、`order`、`system`、`unsupported`。 | | `text` | object | 否 | 当通知描述文本消息时，text 对象提供文本消息的正文内容。 | | `image` | object | 否 | 收到包含媒体（`image` \| `document` \| `audio` \| `video` \| `sticker`）的消息时，WhatsApp Business API 客户端将下载该媒体。媒体下载完成后，系统会向您的 Webhook 发送通知。该消息包含用于标识媒体对象的信息，便于您查找并下载该对象。 | | `video` | object | 否 | 收到包含媒体（`image` \| `document` \| `audio` \| `video` \| `sticker`）的消息时，WhatsApp Business API 客户端将下载该媒体。媒体下载完成后，系统会向您的 Webhook 发送通知。该消息包含用于标识媒体对象的信息，便于您查找并下载该对象。 | | `audio` | object | 否 | 收到包含媒体（`image` \| `document` \| `audio` \| `video` \| `sticker`）的消息时，WhatsApp Business API 客户端将下载该媒体。媒体下载完成后，系统会向您的 Webhook 发送通知。该消息包含用于标识媒体对象的信息，便于您查找并下载该对象。 | | `document` | object | 否 | 收到包含媒体（`image` \| `document` \| `audio` \| `video` \| `sticker`）的消息时，WhatsApp Business API 客户端将下载该媒体。媒体下载完成后，系统会向您的 Webhook 发送通知。该消息包含用于标识媒体对象的信息，便于您查找并下载该对象。 | | `sticker` | object | 否 | 收到包含媒体（`image` \| `document` \| `audio` \| `video` \| `sticker`）的消息时，WhatsApp Business API 客户端将下载该媒体。媒体下载完成后，系统会向您的 Webhook 发送通知。该消息包含用于标识媒体对象的信息，便于您查找并下载该对象。 | | `interactive` | object | 否 | 当客户与您的消息互动时，此对象将包含在消息对象中。 | | `location` | object | 否 | 当您收到用户静态位置的通知时，location 对象会提供该位置的详细信息。 | | `button` | object | 否 | 当消息类型字段设置为 `button` 时，此对象将包含在消息对象中。 | | `contacts` | object\[] | 否 | 数组项说明如下。 | | `reaction` | object | 否 | 当用户使用表情符号对消息做出回应时，消息类型将设置为 `reaction`，并包含此字段。 | | `order` | object | 否 | 当客户下单时，消息类型将设置为 `order`，并包含此字段。 | | `system` | object | 否 | 当消息类型设置为 `system` 时，包含此字段。该对象描述了用户电话号码变更、BSUID 变更或 WhatsApp 上的潜在身份变更。 | | `errors` | object\[] | 否 | 数组项说明如下。 | | `context` | object | 否 | 消息上下文。 | | `referral` | object | 否 | 当用户使用[直达 WhatsApp 广告（Click to WhatsApp）](https://www.facebook.com/business/help/447934475640650)或 [Facebook 公共主页行动号召按钮](https://www.facebook.com/help/977869848936797)向商家发送消息时，此字段作为附件包含在内。 | | `groupId` | string | 否 | WhatsApp 群组 ID。当入站消息在 WhatsApp 群组中发送时包含此字段。 | ##### 嵌套对象参数 展开字段以查看其嵌套参数。 > [accordion] whatsappInboundMessage.customerProfile > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `name` | string | 否 | WhatsApp 账户名称。 | > | `username` | string | 否 | WhatsApp 用户名。 | > [accordion] whatsappInboundMessage.text > > | 参数 | 类型 | 必需 | 说明 | > | - | - | - | - | > | `body` | string | 否 | 消息文本。 | > [accordion] whatsappInboundMessage.image > > | 参数 | 类型 | 必需 | 说明 | > | - | - | - | - | > | `id` | string | 否 | 媒体 ID。如果存储在客户端本地，可用于删除该媒体。 | > | `link` | string | 否 | 下载媒体文件的 URL。请注意，为方便使用者，此链接可在数分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在一个月内下载此文件。 | > | `caption` | string | 否 | 为媒体提供的说明文字。仅在指定时存在。 | > | `filename` | string | 否 | 发送者设备上的文件名。仅在 `document` 媒体消息中存在。 | > | `metadata` | object | 否 | 与 `sticker` 媒体相关的元数据。 | > | `mime_type` | string | 否 | 媒体的 MIME 类型。 | > | `sha256` | string | 否 | 校验和。 | > [accordion] whatsappInboundMessage.video > > | 参数 | 类型 | 必需 | 说明 | > | - | - | - | - | > | `id` | string | 否 | 媒体 ID。如果存储在客户端本地，可用于删除该媒体。 | > | `link` | string | 否 | 下载媒体文件的 URL。请注意，为方便使用者，此链接可在数分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在一个月内下载此文件。 | > | `caption` | string | 否 | 为媒体提供的说明文字。仅在指定时存在。 | > | `filename` | string | 否 | 发送者设备上的文件名。仅在 `document` 媒体消息中存在。 | > | `metadata` | object | 否 | 与 `sticker` 媒体相关的元数据。 | > | `mime_type` | string | 否 | 媒体的 MIME 类型。 | > | `sha256` | string | 否 | 校验和。 | > [accordion] whatsappInboundMessage.audio > > | 参数 | 类型 | 必需 | 说明 | > | - | - | - | - | > | `id` | string | 否 | 媒体 ID。如果存储在客户端本地，可用于删除该媒体。 | > | `link` | string | 否 | 下载媒体文件的 URL。请注意，为方便使用者，此链接可在数分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在一个月内下载此文件。 | > | `caption` | string | 否 | 为媒体提供的说明文字。仅在指定时存在。 | > | `filename` | string | 否 | 发送者设备上的文件名。仅在 `document` 媒体消息中存在。 | > | `metadata` | object | 否 | 与 `sticker` 媒体相关的元数据。 | > | `mime_type` | string | 否 | 媒体的 MIME 类型。 | > | `sha256` | string | 否 | 校验和。 | > [accordion] whatsappInboundMessage.document > > | 参数 | 类型 | 必需 | 说明 | > | - | - | - | - | > | `id` | string | 否 | 媒体 ID。如果存储在客户端本地，可用于删除该媒体。 | > | `link` | string | 否 | 下载媒体文件的 URL。请注意，为方便使用者，此链接可在数分钟内直接访问，但您应始终包含 `X-API-Key` 请求头，以便在一个月内下载此文件。 | > | `caption` | string | 否 | 为媒体提供的说明文字（caption）。仅在指定时出现。 | > | `filename` | string | 否 | 发送者设备上的文件名。仅在 `document` 媒体消息中出现。 | > | `metadata` | object | 否 | 与 `sticker` 媒体相关的元数据。 | > | `mime_type` | string | 否 | 媒体的 MIME 类型。 | > | `sha256` | string | 否 | 校验和。 | > [accordion] whatsappInboundMessage.sticker > > | 参数 | 类型 | 是否必填 | 描述 | > | - | - | - | - | > | `id` | string | 否 | 媒体的 ID。若媒体存储在客户端本地，可用于删除该媒体。 | > | `link` | string | 否 | 用于下载媒体文件的 URL。请注意，为方便使用，此链接在数分钟内可直接访问，但您应始终包含 `X-API-Key` 请求头以便在一个月内下载此文件。 | > | `caption` | string | 否 | 为媒体提供的说明文字（caption）。仅在指定时出现。 | > | `filename` | string | 否 | 发送者设备上的文件名。仅在 `document` 媒体消息中出现。 | > | `metadata` | object | 否 | 与 `sticker` 媒体相关的元数据。 | > | `mime_type` | string | 否 | 媒体的 MIME 类型。 | > | `sha256` | string | 否 | 校验和。 | > [accordion] whatsappInboundMessage.interactive > > | 参数 | 类型 | 是否必填 | 描述 | > | - | - | - | - | > | `type` | string | 否 | 收到的交互式消息类型。
  • `button_reply`：当客户点击按钮时发送。
  • `list_reply`：当客户从列表中选择一项时发送。
  • `nfm_reply`：当客户回复 WhatsApp Flow（Next Feature Messaging）时发送。
  • `call_permission_reply`：当客户回复通话权限请求时发送。
| > | `button_reply` | object | 否 | 当客户点击按钮时发送。当 `type` 为 `button_reply` 时返回。 | > | `list_reply` | object | 否 | 当客户从列表中选择一项时发送。当 `type` 为 `list_reply` 时返回。 | > | `nfm_reply` | object | 否 | 当客户回复 WhatsApp Flow（Next Feature Messaging）时发送。当 `type` 为 `nfm_reply` 时返回。 | > | `call_permission_reply` | object | 否 | 当客户回复通话权限请求时发送。当 `type` 为 `call_permission_reply` 时返回。这发生在 WhatsApp 在用户致电您的企业后提示用户授予回拨权限时。 | > [accordion] whatsappInboundMessage.interactive.button\_reply > > | 参数 | 类型 | 是否必填 | 描述 | > | - | - | - | - | > | `id` | string | 否 | 被点击按钮的唯一 ID。 | > | `title` | string | 否 | 按钮的标题。 | > [accordion] whatsappInboundMessage.interactive.list\_reply > > | 参数 | 类型 | 是否必填 | 描述 | > | - | - | - | - | > | `id` | string | 否 | 所选列表项的唯一 ID。 | > | `title` | string | 否 | 所选列表项的标题。 | > | `description` | string | 否 | 所选行的描述。 | > [accordion] whatsappInboundMessage.interactive.nfm\_reply > > | 参数 | 类型 | 是否必填 | 描述 | > | - | - | - | - | > | `name` | string | 否 | 被回复的 Flow 或表单的名称。 | > | `response_json` | string | 否 | 包含用户对 Flow 回复内容的 JSON 字符串。包含表单字段值和 flow token。 | > | `body` | string | 否 | Flow 回复消息的正文内容。 | > [accordion] whatsappInboundMessage.interactive.call\_permission\_reply > > | 参数 | 类型 | 是否必填 | 说明 | > | - | - | - | - | > | `response` | string | 否 | 客户对通话权限请求的回复。
  • `accept`：用户授予企业回电权限
  • `reject`：用户拒绝企业回电权限
| > | `expiration_timestamp` | integer (int64) | 否 | 通话权限到期的时间戳（秒）。仅当回复为 "accept" 且 is\_permanent 为 false 时存在。 | > | `is_permanent` | boolean | 否 | 权限是永久的还是临时的。
  • `true`：永久授权（永不过期）
  • `false`：临时授权（在 expiration\_timestamp 到期）
| > [accordion] whatsappInboundMessage.location > > | 参数 | 类型 | 是否必填 | 说明 | > | - | - | - | - | > | `latitude` | number (double) | 否 | 所发送位置的纬度。 | > | `longitude` | number (double) | 否 | 所发送位置的经度。 | > | `address` | string | 否 | 位置的地址。 | > | `name` | string | 否 | 位置的名称。 | > | `url` | string | 否 | 用户下载位置信息的网站 URL。 | > [accordion] whatsappInboundMessage.button > > | 参数 | 类型 | 是否必填 | 说明 | > | - | - | - | - | > | `payload` | string | 否 | 客户在互动消息中点击的企业所配置按钮的有效载荷（payload）。 | > | `text` | string | 否 | 按钮文本。 | > [accordion] whatsappInboundMessage.contacts\[] > > | 参数 | 类型 | 是否必填 | 说明 | > | - | - | - | - | > | `addresses` | object\[] | 否 | 数组项说明如下。 | > | `birthday` | string | 否 | `YYYY-MM-DD` 格式化字符串。 | > | `emails` | object\[] | 否 | 数组项说明如下。 | > | `name` | object | 是 | 格式化为 name 对象的联系人全名。 | > | `org` | object | 否 | 格式化为 org 对象的联系人组织信息。 | > | `phones` | object\[] | 否 | 格式化为 phone 对象的联系人电话号码。 | > | `urls` | object\[] | 否 | 格式化为 urls 对象的联系人 URL。 | > | `vcard` | string | 否 | 随分享的联系人有效载荷一起提供的可选 vCard。 | > | `origin` | string | 否 | 当用户为回复索取联系人信息（request-contact-info）消息而分享联系人时，设为 `contact_request`。 | > [accordion] whatsappInboundMessage.contacts\[].addresses\[] > > | 参数 | 类型 | 是否必填 | 说明 | > | - | - | - | - | > | `street` | string | 否 | 街道门牌号和街道名称。 | > | `city` | string | 否 | 城市名称。 | > | `state` | string | 否 | 州/省简写。 | > | `zip` | string | 否 | 邮政编码。 | > | `country` | string | 否 | 国家完整名称。 | > | `country_code` | string | 否 | 两位字母的国家缩写。 | > | `type` | string | 否 | 标准值为 `HOME` 和 `WORK`。 | > [accordion] whatsappInboundMessage.contacts\[].emails\[] > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `email` | string | 否 | 电子邮箱地址。 | > | `type` | string | 否 | 标准值为 `HOME` 和 `WORK`。 | > [accordion] whatsappInboundMessage.contacts\[].name > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `formatted_name` | string | 是 | 完整姓名，通常显示的形式。 | > | `first_name` | string | 否 | 名字。 | > | `last_name` | string | 否 | 姓氏。 | > | `middle_name` | string | 否 | 中间名。 | > | `suffix` | string | 否 | 姓名后缀。 | > | `prefix` | string | 否 | 名前缀（称谓）。 | > [accordion] whatsappInboundMessage.contacts\[].org > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `company` | string | 否 | 联系人所属公司名称。 | > | `department` | string | 否 | 联系人所属部门名称。 | > | `title` | string | 否 | 联系人的职位头衔。 | > [accordion] whatsappInboundMessage.contacts\[].phones\[] > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `phone` | string | 否 | 自动填入已格式化为电话号码的 `wa_id` 值。 | > | `type` | string | 否 | 标准值为 `CELL`、`MAIN`、`IPHONE`、`HOME` 和 `WORK`。 | > | `wa_id` | string | 否 | WhatsApp ID。 | > [accordion] whatsappInboundMessage.contacts\[].urls\[] > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `url` | string | 否 | URL。 | > | `type` | string | 否 | 标准值为 `HOME` 和 `WORK`。 | > [accordion] whatsappInboundMessage.reaction > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `message_id` | string | 是 | 指定包含该反应的已接收消息的 `wamid`。 | > | `emoji` | string | 否 | 发送 `reaction` 消息时为 **必填** 。如果想移除表情符号，请将其设为 `""`。接收来自用户的消息时为 **可选** 。当用户使用表情符号对消息做出回应时，将包含此字段；否则表示用户已移除该表情符号。 | > [accordion] whatsappInboundMessage.order > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `catalog_id` | string | 否 | 目录 ID。 | > | `product_items` | object\[] | 否 | 数组项说明如下。 | > | `text` | string | 否 | 随订单一同发送的文本消息。 | > [accordion] whatsappInboundMessage.order.product\_items\[] > > | 参数 | 类型 | 是否必需 | 说明 | > | - | - | - | - | > | `product_retailer_id` | string | 否 | 商品 SKU 标识符。 | > | `quantity` | integer (int32) | 否 | 商品数量。 | > | `item_price` | number (double) | 否 | 商品单价。 | > | `currency` | string | 否 | 价格币种。[ISO 4217 货币代码](https://en.wikipedia.org/wiki/ISO_4217)。 | > [accordion] whatsappInboundMessage.system > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `body` | string | 否 | 描述系统消息事件。支持的使用场景包括：
  • 电话号码更新：用于用户从旧号码更改为新号码的情况。
  • 身份更新：用于用户身份发生变更的情况。
| > | `wa_id` | string | 否 | Meta 提供的电话号码，不带前导 `+`。在 BSUID 变更时，该字段可能保持不变或被省略。 | > | `user_id` | string | 否 | 针对电话号码或 BSUID 变更，Meta 提供的新业务范围用户 ID（business-scoped user ID）。此字段保留了原始的蛇形命名（snake\_case）。 | > | `parent_user_id` | string | 否 | 针对电话号码或 BSUID 变更的新 Parent BSUID，仅在启用且由 Meta 提供时返回。此字段保留了原始的蛇形命名（snake\_case）。 | > | `previous_user_id` | string | 否 | Meta 提供的先前业务范围用户 ID（business-scoped user ID）。 | > | `previous_parent_user_id` | string | 否 | 先前的 Parent BSUID，仅在启用且由 Meta 提供时返回。 | > | `type` | string | 否 | 支持的类型包括：
  • `user_changed_user_id`：用户更改其 BSUID 的通知。电话号码可以保持不变。
  • `user_changed_number`：用户更改号码通知。
  • `user_identity_changed`：用户身份变更通知。
| > | `user` | string | 否 | \*\*在发生身份更新时添加到 Webhook。\*\*客户的新 WhatsApp 用户 ID。 | > | `new_wa_id` | string | 否 | \*\*在发生电话号码更新时添加到 Webhook。\*\*客户的新 WhatsApp ID。 | > [accordion] whatsappInboundMessage.errors\[] > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `code` | string | 否 | 错误代码。 | > | `title` | string | 否 | 错误标题。 | > | `message` | string | 否 | 错误消息。 | > | `error_data` | object | 否 | 包含以下属性的错误数据对象：
  • `details`：描述错误原因的字符串。示例：`Message type is currently not supported.`。
| > [accordion] whatsappInboundMessage.context > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `forwarded` | boolean | 否 | \*\*如果消息已被转发，则会添加到 Webhook。\*\*如果收到的消息已被转发，则设置为 `true`。 | > | `frequently_forwarded` | boolean | 否 | \*\*如果消息被多次转发，则会添加到 Webhook。\*\*如果收到的消息被转发超过五次，则设置为 `true`。 | > | `from` | string | 否 | \*\*如果消息是对已发送消息的入站回复，则会添加到 Webhook。\*\*已发送消息的发件人的 WhatsApp ID（不带“+”前缀的电话号码）。 | > | `id` | string | 否 | \*\*可选。\*\*入站回复所针对的已发送消息的 `wamid`。`wamid` 是 WhatsApp 平台上的原始消息 ID。 | > | `referred_product` | object | 否 | \*\*商品咨询消息必填。\*\*指定用户正在咨询相关信息的商品。另请参阅 [销售产品与服务](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services)。 | > [accordion] whatsappInboundMessage.context.referred\_product > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `catalog_id` | string | 否 | 目录 ID。 | > | `product_retailer_id` | string | 否 | 商品 SKU 标识符。 | > [accordion] whatsappInboundMessage.referral > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `source_url` | string | 否 | 指定导向用户所点击广告或帖子的 URL。打开此 URL 可跳转至用户查看的广告。 | > | `source_type` | string | 否 | 指定广告来源的类型。支持的值为 "ad" 或 "post"。 | > | `source_id` | string | 否 | 指定广告或帖子的 Meta ID。 | > | `headline` | string | 否 | 指定生成该消息的广告或帖子中使用的标题。 | > | `body` | string | 否 | 生成该消息的广告或帖子的描述或正文。 | > | `media_type` | string | 否 | 用户点击的广告或帖子中包含的媒体内容。支持的值为 "image" 或 "video"。 | > | `image_url` | string | 否 | \*\*当 media\_type 为 "image" 时添加。\*\*包含指向原始图片的 URL。 | > | `video_url` | string | 否 | \*\*当 media\_type 为 "video" 时添加。\*\*包含指向视频的 URL。 | > | `thumbnail_url` | string | 否 | \*\*当 media\_type 为 "video" 时添加。\*\*包含指向所点击视频缩略图的 URL。 | > | `ctwa_clid` | string | 否 | Meta 为点击进入 WhatsApp 的广告生成的点击 ID（Click ID）。 | ## 示例 以下 JSON 是传递给您的接收端的请求体。其中的 ID、电话号码和其他账户值仅用于说明。 > [accordion] 用户更改了 BSUID 但未公开电话号码 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_system_user_id_changed_123", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2026-10-10T08:00:00.000Z", > "whatsappInboundMessage": { > "id": "msg_system_user_id_changed_123", > "wamid": "wamid.EXAMPLE_USER_ID_CHANGED", > "wabaId": "whatsapp-business-account-id", > "to": "+12025550123", > "sendTime": "2026-10-10T08:00:00.000Z", > "type": "system", > "system": { > "type": "user_changed_user_id", > "previous_user_id": "US.13491208655302741918", > "previous_parent_user_id": "US.ENT.11815799212886844830" > } > } > } > ``` > [accordion] 用户更改了号码并带有先前的 BSUID > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_system_number_changed_123", > "type": "whatsapp.inbound_message.received", > "apiVersion": "v2", > "createTime": "2026-10-10T08:00:00.000Z", > "whatsappInboundMessage": { > "id": "msg_system_number_changed_123", > "wamid": "wamid.EXAMPLE_NUMBER_CHANGED", > "wabaId": "whatsapp-business-account-id", > "from": "+12025550124", > "to": "+12025550123", > "sendTime": "2026-10-10T08:00:00.000Z", > "type": "system", > "system": { > "type": "user_changed_number", > "previous_user_id": "US.13491208655302741918", > "previous_parent_user_id": "US.ENT.11815799212886844830", > "new_wa_id": "16315553333" > } > } > } > ``` > [accordion] 入站不支持的消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > ``` > [accordion] 入站文本消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] 由点击 WhatsApp 广告触发的入站文本消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > } > ``` > [accordion] 入站图片消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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://example.com/sample", > "caption": "Go for a walk.", > "id": "592623615738103", > "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=", > "mime_type": "image/jpeg" > } > } > } > ``` > [accordion] 入站视频消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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://example.com/sample", > "caption": "Go for a walk.", > "id": "919306472440541", > "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=", > "mime_type": "video/mp4" > } > } > } > ``` > [accordion] 入站音频消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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://example.com/sample", > "id": "712063723747110", > "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=", > "mime_type": "audio/mpeg" > } > } > } > ``` > [accordion] 入站文档消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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://example.com/sample", > "caption": "PDF example", > "filename": "sample.pdf", > "id": "948915536111569", > "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=", > "mime_type": "application/pdf" > } > } > } > ``` > [accordion] 入站贴纸消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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://example.com/sample", > "id": "729118992174848", > "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=", > "mime_type": "image/webp" > } > } > } > ``` > [accordion] 入站位置消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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://example.com/sample" > } > } > } > ``` > [accordion] 入站联系人消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "recipient@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" > } > ], > "urls": [ > { > "url": "", > "type": "WORK" > } > ] > } > ] > } > } > ``` > [accordion] 入站 Reaction 回应消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "👍" > } > } > } > ``` > [accordion] 入站模板按钮消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] 入站交互式列表回复消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] 入站交互式按钮回复消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] 入站交互式 Flow 响应消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": "+12025550124", > "id": "wamid.HBgNODr..." > } > } > } > ``` > [accordion] 入站订单消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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": 2, > "item_price": 12.5, > "currency": "price-currency" > } > ], > "text": "text-message-sent-along-with-the-order" > }, > "context": { > "from": "+12025550124", > "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o" > } > } > } > ``` > [accordion] 入站商品咨询消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > } > } > ``` > [accordion] 入站请求欢迎消息 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "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" > } > } > ``` 验证签名并持久接收事件后，请返回 `2xx` 响应。耗时任务请异步处理。 ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` 有关各场景的详细演示，请参阅[带注释的示例](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.