whatsapp.inbound_message.received

使用 whatsapp.inbound_message.received 在您的 Webhook 端点处理此事件。

触发条件

在收到 WhatsApp 入站消息时触发。在您配置 Webhook 端点时订阅 whatsapp.inbound_message.received。使用消息 type 来选择其内容对象。媒体、交互式回复、位置、联系人和系统通知具有不同的字段。以下示例展示了这些变体。

语法

YCloud 会向您配置的 Webhook URL 发送一个 HTTP POST 请求。以下结构展示了一种负载变体。尖括号中的值为占位符；其类型列在参数下。可选字段和其他变体在下方说明。

{
  "id": "<ID>",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappInboundMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "to": "<TO>",
    "sendTime": "<SEND_TIME>",
    "type": "<TYPE>",
    "system": {
      "type": "<TYPE>",
      "previous_user_id": "<PREVIOUS_USER_ID>",
      "previous_parent_user_id": "<PREVIOUS_PARENT_USER_ID>"
    }
  }
}

参数

在处理 JSON 请求体之前，请验证 YCloud-Signature HTTP 请求头。请参阅签名验证。

事件外层结构

参数	类型	是否必填	说明
`id`	string	是	事件的唯一 ID。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.inbound_message.received`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	此事件的创建时间，格式为 RFC 3339。例如：`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 格式。
`fromUserId`	string	否	客户的 WhatsApp 商业范围用户 ID（BSUID）。
`fromParentUserId`	string	否	客户的父级 WhatsApp 商业范围用户 ID。
`customerProfile`	object	否	客户的个人资料信息。
`to`	string	否	接收者的电话号码，采用 E.164 格式。
`sendTime`	string (date-time)	否	发送此消息的时间，格式为 RFC 3339。例如：`2022-06-01T12:00:00.000Z`。
`type`	string	否	WhatsApp 入站消息类型。另请参阅 WhatsApp webhook 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）或 Facebook 公共主页行动号召按钮向商家发送消息时，此字段作为附件包含在内。
`groupId`	string	否	WhatsApp 群组 ID。当入站消息在 WhatsApp 群组中发送时包含此字段。

嵌套对象参数

展开字段以查看其嵌套参数。

whatsappInboundMessage.customerProfile

参数	类型	必填	说明
`name`	string	否	WhatsApp 账户名称。
`username`	string	否	WhatsApp 用户名。

whatsappInboundMessage.text

参数	类型	必需	说明
`body`	string	否	消息文本。

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	否	校验和。

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	否	校验和。

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	否	校验和。

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	否	校验和。

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	否	校验和。

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 在用户致电您的企业后提示用户授予回拨权限时。

whatsappInboundMessage.interactive.button_reply

参数	类型	是否必填	描述
`id`	string	否	被点击按钮的唯一 ID。
`title`	string	否	按钮的标题。

whatsappInboundMessage.interactive.list_reply

参数	类型	是否必填	描述
`id`	string	否	所选列表项的唯一 ID。
`title`	string	否	所选列表项的标题。
`description`	string	否	所选行的描述。

whatsappInboundMessage.interactive.nfm_reply

参数	类型	是否必填	描述
`name`	string	否	被回复的 Flow 或表单的名称。
`response_json`	string	否	包含用户对 Flow 回复内容的 JSON 字符串。包含表单字段值和 flow token。
`body`	string	否	Flow 回复消息的正文内容。

whatsappInboundMessage.interactive.call_permission_reply

参数	类型	是否必填	说明
`response`	string	否	客户对通话权限请求的回复。 `accept`：用户授予企业回电权限 `reject`：用户拒绝企业回电权限
`expiration_timestamp`	integer (int64)	否	通话权限到期的时间戳（秒）。仅当回复为 “accept” 且 is_permanent 为 false 时存在。
`is_permanent`	boolean	否	权限是永久的还是临时的。 `true`：永久授权（永不过期） `false`：临时授权（在 expiration_timestamp 到期）

whatsappInboundMessage.location

参数	类型	是否必填	说明
`latitude`	number (double)	否	所发送位置的纬度。
`longitude`	number (double)	否	所发送位置的经度。
`address`	string	否	位置的地址。
`name`	string	否	位置的名称。
`url`	string	否	用户下载位置信息的网站 URL。

whatsappInboundMessage.button

参数	类型	是否必填	说明
`payload`	string	否	客户在互动消息中点击的企业所配置按钮的有效载荷（payload）。
`text`	string	否	按钮文本。

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`。

whatsappInboundMessage.contacts[].addresses[]

参数	类型	是否必填	说明
`street`	string	否	街道门牌号和街道名称。
`city`	string	否	城市名称。
`state`	string	否	州/省简写。
`zip`	string	否	邮政编码。
`country`	string	否	国家完整名称。
`country_code`	string	否	两位字母的国家缩写。
`type`	string	否	标准值为 `HOME` 和 `WORK`。

whatsappInboundMessage.contacts[].emails[]

参数	类型	是否必需	说明
`email`	string	否	电子邮箱地址。
`type`	string	否	标准值为 `HOME` 和 `WORK`。

whatsappInboundMessage.contacts[].name

参数	类型	是否必需	说明
`formatted_name`	string	是	完整姓名，通常显示的形式。
`first_name`	string	否	名字。
`last_name`	string	否	姓氏。
`middle_name`	string	否	中间名。
`suffix`	string	否	姓名后缀。
`prefix`	string	否	名前缀（称谓）。

whatsappInboundMessage.contacts[].org

参数	类型	是否必需	说明
`company`	string	否	联系人所属公司名称。
`department`	string	否	联系人所属部门名称。
`title`	string	否	联系人的职位头衔。

whatsappInboundMessage.contacts[].phones[]

参数	类型	是否必需	说明
`phone`	string	否	自动填入已格式化为电话号码的 `wa_id` 值。
`type`	string	否	标准值为 `CELL`、`MAIN`、`IPHONE`、`HOME` 和 `WORK`。
`wa_id`	string	否	WhatsApp ID。

whatsappInboundMessage.contacts[].urls[]

参数	类型	是否必需	说明
`url`	string	否	URL。
`type`	string	否	标准值为 `HOME` 和 `WORK`。

whatsappInboundMessage.reaction

参数	类型	是否必需	说明
`message_id`	string	是	指定包含该反应的已接收消息的 `wamid`。
`emoji`	string	否	发送 `reaction` 消息时为必填。如果想移除表情符号，请将其设为 `""`。接收来自用户的消息时为可选。当用户使用表情符号对消息做出回应时，将包含此字段；否则表示用户已移除该表情符号。

whatsappInboundMessage.order

参数	类型	是否必需	说明
`catalog_id`	string	否	目录 ID。
`product_items`	object[]	否	数组项说明如下。
`text`	string	否	随订单一同发送的文本消息。

whatsappInboundMessage.order.product_items[]

参数	类型	是否必需	说明
`product_retailer_id`	string	否	商品 SKU 标识符。
`quantity`	integer (int32)	否	商品数量。
`item_price`	number (double)	否	商品单价。
`currency`	string	否	价格币种。ISO 4217 货币代码。

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。

whatsappInboundMessage.errors[]

参数	类型	必填	说明
`code`	string	否	错误代码。
`title`	string	否	错误标题。
`message`	string	否	错误消息。
`error_data`	object	否	包含以下属性的错误数据对象： `details`：描述错误原因的字符串。示例：`Message type is currently not supported.`。

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	否	商品咨询消息必填。指定用户正在咨询相关信息的商品。另请参阅销售产品与服务。

whatsappInboundMessage.context.referred_product

参数	类型	必填	说明
`catalog_id`	string	否	目录 ID。
`product_retailer_id`	string	否	商品 SKU 标识符。

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、电话号码和其他账户值仅用于说明。

用户更改了 BSUID 但未公开电话号码

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

用户更改了号码并带有先前的 BSUID

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

入站不支持的消息

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

入站文本消息

{
  "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..."
    }
  }
}

由点击 WhatsApp 广告触发的入站文本消息

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

入站图片消息

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

入站视频消息

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

入站音频消息

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

入站文档消息

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

入站贴纸消息

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

入站位置消息

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

入站联系人消息

{
  "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": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "recipient@example.com",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<CONTACT_FORMATTED_NAME>",
          "first_name": "<CONTACT_FIRST_NAME>",
          "last_name": "<CONTACT_LAST_NAME>",
          "middle_name": "<CONTACT_MIDDLE_NAME>",
          "suffix": "<CONTACT_SUFFIX>",
          "prefix": "<CONTACT_PREFIX>"
        },
        "org": {
          "company": "<CONTACT_ORG_COMPANY>",
          "department": "<CONTACT_ORG_DEPARTMENT>",
          "title": "<CONTACT_ORG_TITLE>"
        },
        "phones": [
          {
            "phone": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}

入站 Reaction 回应消息

{
  "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": "👍"
    }
  }
}

入站模板按钮消息

{
  "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..."
    }
  }
}

入站交互式列表回复消息

{
  "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": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

入站交互式按钮回复消息

{
  "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": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

入站交互式 Flow 响应消息

{
  "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\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "+12025550124",
      "id": "wamid.HBgNODr..."
    }
  }
}

入站订单消息

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

入站商品咨询消息

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

入站请求欢迎消息

{
  "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/1.1 200 OK

有关各场景的详细演示，请参阅带注释的示例。

开始使用

指南

接口

Webhook reference

whatsapp.inbound_message.received

触发条件

语法

参数

事件外层结构

事件负载

whatsappInboundMessage

嵌套对象参数

示例

​触发条件

​语法

​参数

​事件外层结构

​事件负载

​whatsappInboundMessage

嵌套对象参数

​示例

触发条件

语法

参数

事件外层结构

事件负载

whatsappInboundMessage

示例