whatsapp.echo_message.updated

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

触发条件

当收到 Public REST API Agent 的出站 echo 状态时发生；较晚到达的低优先级状态也可能会被推送。在您配置 Webhook 端点时订阅 whatsapp.echo_message.updated。此事件仅限于通过 Public REST API 接入的 Agent。更新的 echo 不包含消息内容和 type。较晚到达的低优先级状态可能会在 read 之后送达；请记录它们，但不要降级您已存储的消息状态。

语法

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

{
  "id": "<ID>",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappMessage": {
    "id": "<ID>",
    "wamid": "<WAMID>",
    "wabaId": "<WABA_ID>",
    "from": "<FROM>",
    "to": "<TO>",
    "recipientUserId": "<RECIPIENT_USER_ID>",
    "status": "<STATUS>",
    "updateTime": "<UPDATE_TIME>",
    "deliverTime": "<DELIVER_TIME>"
  }
}

参数

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

事件信封

参数	类型	必填	描述
`id`	string	是	事件的唯一 ID。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.echo_message.updated`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	此事件创建的时间，按 RFC 3339 格式化。例如 `2022-06-01T12:00:00.000Z`。

事件有效载荷

参数	类型	必填	描述
`whatsappMessage`	object	是	特定事件的 `whatsappMessage` 有效载荷。

四个通用信封字段为必填项。有效载荷字段取决于事件变体。在每个对象表中，必填仅在其父对象存在时适用。可选字段可以省略；示例并不代表字段是必填的。

whatsappMessage

参数	类型	必填	描述
`id`	string	是	YCloud 消息 ID。可用于关联 created 和 updated echo 事件。
`wamid`	string	否	WhatsApp 平台上的原始消息 ID（若可用）。
`wabaId`	string	否	源回调中的 WhatsApp 商业账户 ID（若可用）。
`from`	string	否	采用 E.164 格式的商业发送方号码（若可用）。
`to`	string	否	当回调通过电话号码标识客户时，采用 E.164 格式的接收方号码。
`recipientUserId`	string	否	接收方的 WhatsApp Business 作用域用户 ID (BSUID)（若回调提供）。
`parentRecipientUserId`	string	否	接收方的父级 WhatsApp Business 作用域用户 ID（若回调提供）。
`type`	string	否	从受支持的服务商回调复制的消息类型。当前取值包括 text、interactive、image、video、audio、document、sticker、location、contacts 和 reaction。客户端应能兼容未来可能增加的值。
`text`	object	否	WhatsApp 消息文本对象（WhatsApp Message Text Object）。
`image`	object	否	从 Meta Business Agent echo 回调复制的媒体元数据。
`video`	object	否	从 Meta Business Agent echo 回调复制的媒体元数据。
`audio`	object	否	从 Meta Business Agent echo 回调复制的媒体元数据。
`document`	object	否	从 Meta Business Agent echo 回调复制的媒体元数据。
`sticker`	object	否	从 Meta Business Agent echo 回调复制的媒体元数据。
`location`	object	否	用于 `location` 消息。
`interactive`	object	否	用于 `interactive` 消息。
`contacts`	object[]	否	数组项说明如下。
`reaction`	object	否	当用户使用 emoji 表情对消息进行回应时，消息类型会被设置为 `reaction`，并包含此字段。
`context`	object	否	用于提及您正在回复的特定消息。回复可以是任何消息类型。
`status`	string	否	WhatsApp 消息状态。取值之一：`accepted`、`failed`、`sent`、`delivered`、`read`。 `accepted`：消息发送请求已被我们的系统接收。 `failed`：您的企业发送的消息发送失败。 `sent`：您的企业发送的消息正在 WhatsApp 系统中传输。 `delivered`：您的企业发送的消息已送达用户设备。 `read`：您的企业发送的消息已被用户阅读。
`errorCode`	string	否	状态为 failed 且提供商提供了错误代码时的源错误代码。
`errorMessage`	string	否	状态为 failed 且提供商提供了错误标题时的源错误标题。
`createTime`	string (date-time)	否	创建事件的源 echo 时间，格式为 RFC 3339。
`updateTime`	string (date-time)	否	更新事件的源状态时间，格式为 RFC 3339。
`sendTime`	string (date-time)	否	创建事件时的源 echo 时间，或当前事件报告为 sent 时的源状态时间。
`deliverTime`	string (date-time)	否	当前事件报告为 delivered 时的源状态时间。
`readTime`	string (date-time)	否	当前事件报告为 read 时的源状态时间。

whatsappMessage.text

参数	类型	必填	说明
`body`	string	是	文本消息必填。文本消息的文本内容，可以包含以 http:// 或 https:// 开头的 URL 以及格式设置。在此处查看可用的格式化选项。如果您在文本中包含 URL 并希望在文本消息中包含预览框（preview_url: true），请确保 URL 以 http:// 或 https:// 开头 — 推荐使用 https:// URL。您必须包含主机名，因为 IP 地址将无法匹配。最大长度：4096 个字符。最大长度：`4096`。
`preview_url`	boolean	否	默认情况下，WhatsApp 会识别 URL 并使其可点击，但您也可以包含带有链接更多信息的预览框。如果希望包含 URL 预览框，请将此字段设置为 true。大多数情况下，当您发送 URL、将 preview_url 设置为 true 并提供包含 http 或 https 链接的 body 对象时，接收者将看到可点击的 URL。URL 预览仅在发生以下情况之一后才会呈现：企业向用户发送了消息模板。用户通过“点击聊天”链接发起了对话。用户将企业电话号码添加到其通讯录并主动发起了对话。默认值：`false`。

whatsappMessage.image

参数	类型	必填	说明
`id`	string	否	回调中提供的提供商媒体 ID。
`link`	string	否	提供商媒体 URL（回调提供时包含）。
`caption`	string	否	媒体说明（回调提供时包含）。
`filename`	string	否	原始文件名（回调提供时包含）。
`mime_type`	string	否	从回调复制的提供商 MIME 类型。

whatsappMessage.video

参数	类型	必填	说明
`id`	string	否	提供商媒体 ID（回调提供时包含）。
`link`	string	否	提供商媒体 URL（回调提供时包含）。
`caption`	string	否	媒体说明（回调提供时包含）。
`filename`	string	否	原始文件名（回调提供时包含）。
`mime_type`	string	否	从回调复制的提供商 MIME 类型。

whatsappMessage.audio

参数	类型	必填	说明
`id`	string	否	提供商媒体 ID（回调提供时包含）。
`link`	string	否	提供商媒体 URL（回调提供时包含）。
`caption`	string	否	媒体说明（回调提供时包含）。
`filename`	string	否	原始文件名（回调提供时包含）。
`mime_type`	string	否	从回调复制的提供商 MIME 类型。

whatsappMessage.document

参数	类型	必填	说明
`id`	string	否	提供商媒体 ID（回调提供时包含）。
`link`	string	否	提供商媒体 URL（回调提供时包含）。
`caption`	string	否	媒体说明（回调提供时包含）。
`filename`	string	否	原始文件名（回调提供时包含）。
`mime_type`	string	否	从回调复制的提供商 MIME 类型。

whatsappMessage.sticker

参数	类型	必填	说明
`id`	string	否	提供商媒体 ID（回调提供时包含）。
`link`	string	否	提供商媒体 URL（回调提供时包含）。
`caption`	string	否	媒体说明（回调提供时包含）。
`filename`	string	否	原始文件名（回调提供时包含）。
`mime_type`	string	否	从回调复制的提供商 MIME 类型。

whatsappMessage.location

参数	类型	必填	说明
`latitude`	number (double)	是	地理位置的纬度。
`longitude`	number (double)	是	地理位置的经度。
`name`	string	否	地理位置名称。
`address`	string	否	地理位置的地址。仅在存在 `name` 时显示。

whatsappMessage.interactive

参数	类型	必填	说明
`type`	string	否	必填。要发送的互动消息类型。 `button`：用于回复按钮（Reply Buttons）。 `list`：用于列表消息（List Messages）。 `cta_url`：用于行动号召 (CTA) URL 按钮消息。 `product`：用于单商品消息（Single Product Messages）。 `product_list`：用于多商品消息（Multi-Product Messages）。 `catalog_message`：用于商品目录消息（Catalog Messages）。 `location_request_message`：用于位置请求消息（Location Request Messages）。 `order_details`：用于订单详情消息（Order Details Messages）。 `order_status`：用于订单状态消息（Order Status Messages）。 `voice_call`：用于语音通话消息（Voice Call Messages）。 `flow`：用于 Flow 消息。
`action`	object	否	必填。希望用户阅读 `interactive` 消息后执行的操作。
`body`	object	否	对于类型 `product` 为可选。其他消息类型必填。
`header`	object	否	对于类型 `product_list` 必填。其他类型可选。
`footer`	object	否	可选。包含消息页脚的对象。

whatsappMessage.interactive.action

参数	类型	是否必需	描述
`buttons`	object[]	否	回复按钮必填。最多可包含 3 个按钮。
`button`	string	否	列表消息必填。按钮内容。不能为空字符串，且在消息中必须唯一。支持 Emoji，不支持 Markdown。最大长度：20 个字符。最大长度：`20`。
`catalog_id`	string	否	单商品消息和多商品消息必填。关联到您的 WhatsApp 商业账户的 Facebook 目录唯一标识符。该 ID 可以通过 Meta Commerce Manager 获取。
`product_retailer_id`	string	否	单商品消息和多商品消息必填。目录中商品的唯一标识符。
`sections`	object[]	否	列表消息和多商品消息必填。分区对象数组。最少 1 个，最多 10 个。
`name`	string	否	操作名称。行动号召 (CTA) 按钮必填。 `cta_url`：用于行动号召 (CTA) URL 按钮。 `catalog_message`：用于商品目录消息。 `send_location`：用于位置请求按钮。 `flow`：用于 Flow 按钮。 `review_and_pay`：用于订单详情按钮。 `review_order`：用于订单状态按钮。 `voice_call`：用于语音通话按钮。
`parameters`	object	否	操作参数。行动号召 (CTA) 按钮必填。

whatsappMessage.interactive.action.buttons[]

参数	类型	是否必需	描述
`type`	string	否	唯一支持的类型是 `reply`（用于回复按钮）。
`reply`	object	否	对象字段如下所示。

whatsappMessage.interactive.action.buttons[].reply

参数	类型	必填	说明
`title`	string	否	按钮标题。不能为空字符串，且在消息中必须唯一。支持表情符号（Emoji），不支持 Markdown。最大长度：20 个字符。最大长度：`20`。
`id`	string	否	按钮的唯一标识符。当用户点击该按钮时，此 ID 会在 Webhook 中返回。最大长度：256 个字符。设置 ID 时首尾不能包含空格。最大长度：`256`。

whatsappMessage.interactive.action.sections[]

参数	类型	必填	说明
`title`	string	否	当消息包含多个分区（Section）时必填。分区标题。最大长度：24 个字符。最大长度：`24`。
`rows`	object[]	否	包含行列表。所有分区总共最多可包含 10 行。每行必须有一个标题（最大长度：24 个字符）和一个 ID（最大长度：200 个字符）。您可以添加描述（最大长度：72 个字符），此项为可选。
`product_items`	object[]	否	多商品消息（Multi-Product Messages）必填。商品对象数组。每个分区至少包含 1 个商品，所有分区总计最多包含 30 个商品。

whatsappMessage.interactive.action.sections[].rows[]

参数	类型	必填	说明
`id`	string	否	唯一行 ID。最大长度：200 个字符。最大长度：`200`。
`title`	string	否	行标题内容。最大长度：24 个字符。最大长度：`24`。
`description`	string	否	行描述内容。最大长度：72 个字符。最大长度：`72`。

whatsappMessage.interactive.action.sections[].product_items[]

参数	类型	必填	说明
`product_retailer_id`	string	否	多商品消息必填。目录中商品的唯一标识符。

whatsappMessage.interactive.action.parameters

参数	类型	必填	说明
`display_text`	string	否	CTA URL 按钮的文本。最大长度：20 字节。最大长度：`20`。
`url`	string	否	CTA URL 按钮的 URL。
`thumbnail_product_retailer_id`	string	否	商品 SKU 编号。在 Commerce Manager 中标记为 Content ID 。该商品的缩略图将用作消息的标头图片。
`flow_message_version`	string	否	用于 `flow` 按钮。值必须为 “3”。
`flow_token`	string	否	用于 `flow` 按钮。由企业生成并作为标识符的 Flow 令牌（Flow token）。默认为 `unused`。
`flow_id`	string	否	用于 `flow` 按钮时按条件必填。由 WhatsApp 提供的 Flow 唯一 ID。不能与 `flow_name` 参数同时使用。
`flow_name`	string	否	`flow` 按钮有条件必填。您创建的 Flow 的名称。不能与 `flow_id` 参数一起使用。更改 Flow 名称将需要更新此参数以匹配新名称。
`flow_cta`	string	否	`flow` 按钮必填。CTA 按钮上的文本。例如：“Open flow!”。最大长度：20 个字符。最大长度：`20`。
`flow_action`	string	否	用于 `flow` 按钮。`navigate` 或 `data_exchange` 之一。默认为 `navigate`。
`flow_action_payload`	object	否	如果 `flow_action` 为 `navigate` 则必填。否则应省略。
`reference_id`	string	否	`review_and_pay` 按钮必填。由商家提供的订单唯一标识符。区分大小写，不能为空字符串，且只能包含英文字母、数字、下划线、短划线或点号，长度不能超过 35 个字符。对于特定商家，每个 order_details 消息的 `reference_id` 必须是唯一的。如果需要针对同一订单发送多条 order_details 消息，建议在 reference_id 中包含序号（例如 “BM345A-12”）以确保 reference_id 的唯一性。
`type`	string	否	`review_and_pay` 按钮必填。此订单中支付的商品类型。目前支持的选项有 `digital-goods` 和 `physical-goods`。
`beneficiaries`	object[]	否	`review_and_pay` 按钮必填。此订单的收款方数组。收款方是用于运送订单中实物商品的预期收件人。收款方信息不会向用户显示，但出于法律和合规原因需要提供。
`currency`	string	否	`review_and_pay` 按钮必填。此订单的货币。目前唯一支持的值为 `INR`。
`total_amount`	object	否	`review_and_pay` 按钮必填。此订单的总金额。
`order`	object	否	`review_and_pay` 或 `review_order` 按钮必填。对于 `review_and_pay` 按钮，提供订单 `status`、`items`、`subtotal`、`tax` 等。对于 `review_order` 按钮，仅提供订单 `status` 和 `description`。
`payment_settings`	object[]	否	`review_and_pay` 按钮必填。订单的支付设置。

whatsappMessage.interactive.action.parameters.flow_action_payload

参数	类型	是否必填	说明
`screen`	string	否	首先显示的页面的 ID。必须为 entry 页面。
`data`	object	否	Flow 第一个页面的可选输入数据。如果提供，此项必须是非空对象。

whatsappMessage.interactive.action.parameters.beneficiaries[]

参数	类型	是否必填	说明
`name`	string	是	接收实物商品的个人或企业名称。长度不能超过 200 个字符。最大长度：`200`。
`address_line1`	string	是	配送地址（门牌号/楼号、街道名称等）。不能超过 100 个字符。最大长度：`100`。
`address_line2`	string	否	配送地址（地标、区域等）。不能超过 100 个字符。最大长度：`100`。
`city`	string	是	城市名称。
`state`	string	是	州/省名称。
`country`	string	是	国家名称。目前唯一支持的值是 `India`。
`postal_code`	string	是	配送地址的 6 位邮政编码。最小长度：`6`。最大长度：`6`。

whatsappMessage.interactive.action.parameters.total_amount

参数	类型	必填	描述
`offset`	integer (int32)	是	对于 `INR` 必须为 `100`。
`value`	integer (int32)	是	表示金额乘以偏移量（offset）后的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅用于 `tax`、`shipping` 或 `discount`。金额描述。最大字符限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅用于 `discount`。用于定义促销/优惠订单的文本。如果订单包含优惠，商家需要定义此信息。最大字符限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order

参数	类型	必填	描述
`status`	string	否	在 `order_details` 消息中唯一支持的值为 `pending`。在 `order_status` 消息中，`status` 可以为：`pending`、`processing`、`partially_shipped`、`shipped`、`completed` 或 `canceled`。
`type`	string	否	唯一支持的值是 `quick_pay`。传入此字段时，我们会在订单详情气泡中隐藏“Review and Pay”按钮，仅显示“Pay Now”按钮。
`catalog_id`	string	否	商家使用的 Facebook 目录的唯一标识符。如果不提供此字段，则必须在 items 对象内提供以下字段：`country_of_origin`、`importer_name` 和 `importer_address`。
`items`	object[]	否	订单中的商品数组。
`subtotal`	object	否	该值必须等于 `order.amount.value` * `order.amount.quantity` 的总和。
`tax`	object	否	此订单的税费信息。
`shipping`	object	否	订单的运费。
`discount`	object	否	此订单的折扣金额。
`expiration`	object	否	此订单的过期时间。
`description`	string	否	可选。用于分享状态相关信息的文本。在发送取消通知时可能很有用。最大字符限制为 120 个字符。最大长度：`120`。

whatsappMessage.interactive.action.parameters.order.items[]

参数	类型	是否必填	说明
`retailer_id`	string	否	目录中订单商品的 Content ID。
`name`	string	是	向用户展示的商品名称。不能超过 60 个字符。最大长度：`60`。
`image`	object	否	向用户展示的商品自定义图片。
`amount`	object	是	商品单价。
`sale_amount`	object	否	商品折后单价。应小于原金额。如果包含此字段，将用于计算小计金额。
`quantity`	integer (int32)	是	订单中的商品数量。
`country_of_origin`	string	否	如果不存在 `catalog_id`，则为必填项。商品的原产国。
`importer_name`	string	否	如果不存在 `catalog_id`，则为必填项。进口商公司名称。
`importer_address`	string	否	如果不存在 `catalog_id`，则为必填项。进口商公司地址。

whatsappMessage.interactive.action.parameters.order.items[].image

参数	类型	是否必填	说明
`id`	string	否	当媒体已上传到 WhatsApp 服务器时使用。提供从 WhatsApp 媒体上传 API 获取的媒体对象 ID（https://docs.ycloud.com/reference/whatsapp_media-upload#/）。注意：必须提供 `id` 或 `link` 之一。如果两者都提供，则以 `id` 为准。
`link`	string	否	当直接从您的服务器发送媒体时使用。要发送的媒体的协议和 URL。仅适用于 HTTP/HTTPS URL。注意：WhatsApp Cloud API 会将媒体资源缓存 10 分钟。为确保获取最新内容，请在 URL 中添加随机查询字符串。注意：必须提供 `id` 或 `link` 之一。如果两者都提供，则以 `id` 为准，`link` 将被忽略。
`caption`	string	否	描述指定的 `image`、`gif`、`video` 或 `document` 媒体。不适用于 `header` 或 `template` 消息的 `interactive`。
`filename`	string	否	描述特定文档的文件名。仅适用于 `document` 媒体。

whatsappMessage.interactive.action.parameters.order.items[].amount

参数	类型	是否必填	说明
`offset`	integer (int32)	是	对于 `INR` 必须为 `100`。
`value`	integer (int32)	是	表示金额值乘以偏移量后的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅用于 `tax`、`shipping` 或 `discount`。金额的描述。最大字符限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅适用于 `discount`。用于定义激励订单的文本。如果订单包含激励，商家需要定义此信息。最大字符限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order.items[].sale_amount

参数	类型	是否必填	说明
`offset`	integer (int32)	是	对于 `INR`，必须为 `100`。
`value`	integer (int32)	是	表示金额乘以 offset（偏移量）的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅适用于 `tax`、`shipping` 或 `discount`。金额说明。最大字符限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅适用于 `discount`。用于定义激励订单的文本。如果订单包含激励，商家需要定义此信息。最大字符限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order.subtotal

参数	类型	是否必填	说明
`offset`	integer (int32)	是	对于 `INR`，必须为 `100`。
`value`	integer (int32)	是	表示金额乘以 offset（偏移量）的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅适用于 `tax`、`shipping` 或 `discount`。金额说明。最大字符限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅适用于 `discount`。用于定义激励订单的文本。如果订单包含激励，商家需要定义此信息。最大字符限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order.tax

参数	类型	是否必填	说明
`offset`	integer (int32)	是	对于 `INR`，必须为 `100`。
`value`	integer (int32)	是	表示金额乘以 offset（偏移量）的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅适用于 `tax`、`shipping` 或 `discount`。金额说明。最大字符限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅适用于 `discount`。用于定义激励订单的文本。如果订单包含激励，商家需要定义此信息。最大字符限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order.shipping

参数	类型	是否必填	说明
`offset`	integer (int32)	是	对于 `INR`，必须为 `100`。
`value`	integer (int32)	是	表示金额乘以 offset（偏移量）的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅适用于 `tax`、`shipping` 或 `discount`。金额的描述。最大字符数限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅适用于 `discount`。用于定义促销/优惠订单的文本。如果订单包含优惠激励，商家需要定义此信息。最大字符数限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order.discount

参数	类型	必填	说明
`offset`	integer (int32)	是	对于 `INR`，必须为 `100`。
`value`	integer (int32)	是	表示金额数值乘以 offset 后的正整数。例如，₹12.34 的值为 1234。
`description`	string	否	仅适用于 `tax`、`shipping` 或 `discount`。金额的描述。最大字符数限制为 60 个字符。最大长度：`60`。
`discount_program_name`	string	否	仅适用于 `discount`。用于定义促销/优惠订单的文本。如果订单包含优惠激励，商家需要定义此信息。最大字符数限制为 60 个字符。最大长度：`60`。

whatsappMessage.interactive.action.parameters.order.expiration

参数	类型	必填	说明
`timestamp`	string	是	表示订单过期时间的 UTC 秒级时间戳字符串。最小阈值为 300 秒。
`description`	string	否	过期的文本说明。最大长度：`120`。

whatsappMessage.interactive.action.parameters.payment_settings[]

参数	类型	必填	说明
`type`	string	是	必须设置为 `payment_gateway`。
`payment_gateway`	object	是	描述支付账户信息的对象。

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway

参数	类型	必填	说明
`type`	string	是	支付类型。如果您已关联 BillDesk、Razorpay、PayU 或 Zaakpay 支付网关以接收付款，则必须将其设置为 `billdesk`、`razorpay`、`payu` 或 `zaakpay`。
`configuration_name`	string	是	此订单所使用的预配置支付配置名称，且不得超过 60 个字符。该值必须与 WhatsApp 商务管理平台（WhatsApp Business Manager）上设置的支付配置相匹配。最大长度：`60`。
`billdesk`	object	否	BillDesk 的附加信息。用户自定义字段 (extra) 用于存储与特定订单对应的任何信息。每个 extra 字段的最大字符限制为 120。
`payu`	object	否	PayU 的附加信息。用户自定义字段 (udf) 用于存储与特定订单对应的任何信息。每个 UDF 字段的最大字符限制为 255。
`razorpay`	object	否	Razorpay 的附加信息。
`zaakpay`	object	否	Zaakpay 的附加信息。用户自定义字段（extra）用于存储与特定订单对应的任何信息。每个 extra 字段的最大字符限制为 180。

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.billdesk

参数	类型	是否必填	说明
`additional_info1`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。
`additional_info2`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。
`additional_info3`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。
`additional_info4`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。
`additional_info5`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。
`additional_info6`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。
`additional_info7`	string	否	针对 BillDesk 的此订单用户自定义信息。最大长度：`120` 个字符。

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.payu

参数	类型	是否必填	说明
`udf1`	string	否	针对 PayU 的此订单用户自定义信息。最大长度：`255` 个字符。
`udf2`	string	否	针对 PayU 的此订单用户自定义信息。最大长度：`255` 个字符。
`udf3`	string	否	针对 PayU 的此订单用户自定义信息。最大长度：`255` 个字符。
`udf4`	string	否	针对 PayU 的此订单用户自定义信息。最大长度：`255` 个字符。

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.razorpay

参数	类型	是否必填	说明
`receipt`	string	否	对应此订单的收据编号，供您内部参考使用。支持的最大长度为 40 个字符，最小长度需大于 0 个字符。
`notes`	object	否	该对象可以是键值对，最多包含 15 个键，每个值的长度限制为 256 个字符。

whatsappMessage.interactive.action.parameters.payment_settings[].payment_gateway.zaakpay

参数	类型	是否必填	说明
`extra1`	string	否	针对 Zaakpay 的此订单用户自定义信息。最大长度：`180` 个字符。
`extra2`	string	否	针对 Zaakpay 的此订单用户自定义信息。最大长度：`180` 个字符。

whatsappMessage.interactive.body

参数	类型	必填	说明
`text`	string	否	消息的正文内容。支持表情符号和 markdown。最大长度：1024 个字符。最大长度：`1024`。

whatsappMessage.interactive.header

参数	类型	必填	说明
`type`	string	否	必填。要使用的标头类型。 `text`：用于列表消息、回复按钮和多商品消息。 `video`：用于回复按钮。 `image`：用于回复按钮。 `document`：用于回复按钮。
`text`	string	否	标头文本。格式允许使用表情符号，但不支持 markdown。最大长度：`60`。
`image`	object	否	用于 `image`、`gif`、`video`、`audio`、`document` 或 `sticker` 消息。另请参阅 Supported Media Types。
`video`	object	否	用于 `image`、`gif`、`video`、`audio`、`document` 或 `sticker` 消息。另请参阅 Supported Media Types。
`document`	object	否	用于 `image`、`gif`、`video`、`audio`、`document` 或 `sticker` 消息。另请参阅 Supported Media Types。

whatsappMessage.interactive.header.image

参数	类型	必填	说明
`id`	string	否	当媒体已上传到 WhatsApp 服务器时使用。提供从 WhatsApp 媒体上传 API 获取的媒体对象 ID（https://docs.ycloud.com/reference/whatsapp_media-upload#/）。注意：必须提供 `id` 或 `link` 之一。如果两者都提供，则以 `id` 为准。
`link`	string	否	直接从您的服务器发送媒体时使用。要发送的媒体的协议和 URL。仅支持 HTTP/HTTPS URL。注意：WhatsApp Cloud API 会将媒体资源缓存 10 分钟。为确保获取最新内容，请在 URL 中添加随机查询字符串。注意：必须提供 `id` 或 `link` 之一。如果两者都提供，则以 `id` 为准，`link` 将被忽略。
`caption`	string	否	描述指定的 `image`、`gif`、`video` 或 `document` 媒体。不适用于 `template` 或 `interactive` 消息的 `header`。
`filename`	string	否	描述特定文档的文件名。仅适用于 `document` 媒体。

whatsappMessage.interactive.header.video

参数	类型	必填	说明
`id`	string	否	当媒体已上传到 WhatsApp 服务器时使用。提供从 WhatsApp 媒体上传 API 获取的媒体对象 ID（https://docs.ycloud.com/reference/whatsapp_media-upload#/）。注意：必须提供 `id` 或 `link` 之一。如果两者都提供，则以 `id` 为准。
`link`	string	否	当直接从您的服务器发送媒体时使用此项。待发送媒体的协议和 URL。仅支持 HTTP/HTTPS URL。注意：WhatsApp Cloud API 会将媒体资源缓存 10 分钟。为确保内容最新，请在 URL 中添加随机查询字符串。注意：必须提供 `id` 或 `link` 之一。如果两者均提供，则优先使用 `id`，`link` 将被忽略。
`caption`	string	否	描述指定的 `image`、`gif`、`video` 或 `document` 媒体。不适用于 `template` 或 `interactive` 消息的 `header`。
`filename`	string	否	描述特定文档的文件名。仅适用于 `document` 媒体。

whatsappMessage.interactive.header.document

参数	类型	必填	说明
`id`	string	否	当媒体上传到 WhatsApp 服务器时使用此项。提供从 WhatsApp 媒体上传 API 获取的媒体对象 ID（https://docs.ycloud.com/reference/whatsapp_media-upload#/）。注意：必须提供 `id` 或 `link` 之一。如果两者均提供，则优先使用 `id`。
`link`	string	否	当直接从您的服务器发送媒体时使用此项。待发送媒体的协议和 URL。仅支持 HTTP/HTTPS URL。注意：WhatsApp Cloud API 会将媒体资源缓存 10 分钟。为确保内容最新，请在 URL 中添加随机查询字符串。注意：必须提供 `id` 或 `link` 之一。如果两者均提供，则优先使用 `id`，`link` 将被忽略。
`caption`	string	否	描述指定的 `image`、`gif`、`video` 或 `document` 媒体。不适用于 `template` 或 `interactive` 消息的 `header`。
`filename`	string	否	描述特定文档的文件名。仅适用于 `document` 媒体。

whatsappMessage.interactive.footer

参数	类型	必填	说明
`text`	string	否	页脚内容。支持表情符号和 Markdown。支持链接。最大长度：60 个字符。最大长度：`60`。

whatsappMessage.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	否	当用户回复请求联系人信息消息而共享联系人时，设为 `contact_request`。

whatsappMessage.contacts[].addresses[]

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

whatsappMessage.contacts[].emails[]

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

whatsappMessage.contacts[].name

参数	类型	是否必需	说明
`formatted_name`	string	是	完整姓名，按通常显示的方式呈现。
`first_name`	string	否	名。
`last_name`	string	否	姓。
`middle_name`	string	否	中间名。
`suffix`	string	否	姓名后缀。
`prefix`	string	否	名前缀。

whatsappMessage.contacts[].org

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

whatsappMessage.contacts[].phones[]

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

whatsappMessage.contacts[].urls[]

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

whatsappMessage.reaction

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

whatsappMessage.context

参数	类型	是否必需	说明
`message_id`	string	否	指定您正在回复的消息的 `wamid`。`wamid` 是 WhatsApp 平台上的原始消息 ID。

示例

以下 JSON 是发送至接收端的消息体。ID、电话号码和其他账户值仅用于说明。

回显消息已送达

通过 id 或 wamid 与已创建事件进行关联。更新事件会省略消息内容和类型。

{
  "id": "evt_example_echo_delivered",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "delivered",
    "updateTime": "2026-09-09T02:00:01.000Z",
    "deliverTime": "2026-09-09T02:00:01.000Z"
  }
}

Echo 消息已读

通过 id 或 wamid 与已创建事件进行关联。更新事件会省略消息内容和类型。

{
  "id": "evt_example_echo_read",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "read",
    "updateTime": "2026-09-09T02:00:02.000Z",
    "readTime": "2026-09-09T02:00:02.000Z"
  }
}

已读后收到延迟的 sent 状态

级别较低的源状态可能会在已读之后到达。记录该事件即可，切勿降级您当前的消息状态。

{
  "id": "evt_example_echo_sent",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "sent",
    "updateTime": "2026-09-09T02:00:00.000Z",
    "sendTime": "2026-09-09T02:00:00.000Z"
  }
}

失败的 echo 消息

这是一条单独的失败消息，并非由已读状态流转而来。失败更新会在可用时包含源错误详情。

{
  "id": "evt_example_echo_failed",
  "type": "whatsapp.echo_message.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-09T02:00:03.000Z",
  "whatsappMessage": {
    "id": "FAILED_MESSAGE_ID",
    "wamid": "wamid.FAILED_EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+12025550124",
    "to": "+12025550123",
    "recipientUserId": "GB.898232076600896",
    "status": "failed",
    "errorCode": "131000",
    "errorMessage": "Provider failure",
    "updateTime": "2026-09-09T02:00:03.000Z"
  }
}

在验证签名并持久化接收事件后，返回 2xx 响应。耗时较长的工作请进行异步处理。

HTTP/1.1 200 OK

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

开始使用

指南

接口

Webhook reference

whatsapp.echo_message.updated

触发条件

语法

参数

事件信封

事件有效载荷

whatsappMessage

示例

​触发条件

​语法

​参数

​事件信封

​事件有效载荷

​whatsappMessage

​示例

触发条件

语法

参数

事件信封

事件有效载荷

whatsappMessage

示例