Skip to main content
如需查看完整的基于 Schema 衍生的目录,请参阅所有示例。

功能简介

处理 WhatsApp、Messenger 和 SMS 入站消息,以及 WhatsApp 营销偏好设置。

准备工作

  • 在您的应用程序中创建一个公开的 HTTPS 终端节点。
  • 为您所需的事件类型配置 YCloud Webhook 终端节点。
  • 安全存储终端节点签名密钥。
  • 确保事件处理具备幂等性。

工作原理

事件发生时,YCloud 会发送 HTTP POST 请求。验证签名,持久化记录事件,返回 2xx 响应,并异步处理耗时任务。

请求

以下场景展示了发送到您的 Webhook URL 的请求。将事件 id 作为交付标识符,并使用 type 路由有效载荷。

响应

接收事件后返回 2xx 状态。
有关终端节点设置、签名验证和重试机制,请参阅配置 Webhook。

入站不支持的消息

在此情况下,您的 Webhook 终端节点收到了不支持的入站消息:
  • type 设置为 unsupported。
  • errors 说明了为什么该消息不受支持或不可用。
  • unsupported.type 标识了消息类别,例如 poll_creation、poll_update、edit 或 pin。

请求

响应

在持久化接收事件后确认交付。

说明

  • 带有 Message type unknown 的错误 131051 表示 WhatsApp Cloud API 不支持该消息类型。
  • 带有 This message is currently unavailable. 的错误 131060 表示 WhatsApp 无法提供该消息内容。
  • unsupported.type 标识了常规类别。它不包含原始消息内容。
  • 有关易读的消息类型列表,请参阅收件箱中不受支持的消息。有关当前有效载荷规范,请参阅 Meta 的不受支持的消息 Webhook 参考。

入站文本消息

在此情况下,您的 Webhook 终端节点收到了入站文本消息:
  • 包含用户发送的纯文本。
  • 在 context 中包含所提及消息的信息。

请求

响应

在持久化接收事件后确认交付。

说明

  • 入站消息是指客户向您的商业电话号码发送的消息。
  • context(可选)包含所提及消息的信息,通常用于回复用户或您的企业先前发送的消息。
    • context.from 是发送所提及消息的用户的 WhatsApp ID(不带“+”前缀的电话号码)。
    • context.id 是所提及消息在 WhatsApp 平台上的原始 ID,以 wamid. 开头。

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

在此情况下,您的 Webhook 终端节点收到了由点击 WhatsApp 广告触发的入站文本消息:
  • 包含纯文本。
  • 包含有关广告的信息。

请求

响应

在持久化接收事件后确认交付。

说明

入站图片消息

在此情况下,您的 Webhook 终端节点收到了入站图片消息:
  • 包含图片 URL。
  • 包含用于描述此图片的说明文字。

请求

响应

在持久化接收事件后确认交付。

说明

  • 为方便消费者,image.link 可在几分钟内直接访问,但您应始终包含 X-API-Key 请求头以在 30 天内下载此文件。

入站视频消息

在此情况下,您的 Webhook 终端节点收到了入站视频消息:
  • 包含视频 URL。
  • 包含用于描述此视频的说明文字。

请求

响应

在持久化接收事件后确认交付。

说明

  • 为方便消费者,video.link 可在几分钟内直接访问,但您应始终包含 X-API-Key 请求头以在 30 天内下载此文件。

入站音频消息

在此情况下,您的 Webhook 终端节点收到了入站音频消息:
  • 包含音频 URL。

请求

响应

在持久化接收事件后确认交付。

说明

  • 为方便消费者,audio.link 可在几分钟内直接访问,但您应始终包含 X-API-Key 请求头以在 30 天内下载此文件。

入站文档消息

在此情况下,您的 Webhook 终端节点收到了入站文档消息:
  • 包含文档 URL。
  • 包含用于描述此文档的说明文字。

请求

响应

在持久化接收事件后确认交付。

说明

  • 为方便消费者,document.link 可在几分钟内直接访问,但您应始终包含 X-API-Key 请求头以在 30 天内下载此文件。

入站贴纸消息

在此情况下,您的 Webhook 终端节点收到了入站贴纸消息:
  • 包含贴纸 URL。

请求

响应

在持久化接收事件后确认送达。

说明

  • 为了方便使用者,sticker.link 可以在几分钟内直接访问,但您应始终包含 X-API-Key 请求头以在 30 天内下载此文件。

接收位置消息

在这种情况下,您的 Webhook 端点收到了一条接收位置消息:
  • 包含该地点的纬度和经度。
  • 包含该地点的名称、地址和 URL。

请求

响应

在持久化接收事件后确认送达。

说明

根据 type 路由事件,通过 id 进行去重,并将耗时或易出错的操作移至异步处理器。

接收联系人消息

在这种情况下,您的 Webhook 端点收到了一条接收联系人消息:
  • 包含一个联系人及其地址、生日、电子邮件、姓名、电话及其他联系人字段。
  • 当用户响应请求联系人信息消息而共享联系人时,包含 origin: contact_request。

请求

响应

在持久化接收事件后确认送达。

说明

根据 type 路由事件,通过 id 进行去重,并将耗时或易出错的操作移至异步处理器。

接收回应消息

在这种情况下,您的 Webhook 端点收到了一条接收回应消息:
  • 包含用户所回应的消息 ID。
  • 包含表情符号。

请求

响应

在持久化接收事件后确认送达。

说明

  • 当用户使用表情符号回应消息时,会出现 emoji。如果不存在,则表示用户移除了对消息的表情符号回应。

接收模板按钮消息

在这种情况下,您的 Webhook 端点收到了一条接收模板按钮消息:
  • 包含您在发送消息模板时所用模板的按钮 text。
  • 包含您在发送消息模板时提供的按钮 payload。
  • 包含您发送的消息模板的 wamid(context.wamid)。

请求

响应

在持久化接收事件后确认送达。

说明

根据 type 路由事件,通过 id 进行去重,并将耗时或易出错的操作移至异步处理器。

接收互动列表回复消息

在这种情况下,您的 Webhook 端点收到了一条接收互动列表回复消息:
  • interactive 字段包含用户在您之前发送的互动消息中点击的列表回复。
  • context 字段包含您之前向用户发送的互动消息的相关信息。
点击按钮选择一项。 收件人通过在您之前发送的互动消息中选择一项来回复您的消息。

请求

响应

在持久化接收事件后确认送达。

说明

  • context 包含您之前发送的互动消息的相关信息。
    • context.from 是发送该互动消息者的 WhatsApp ID(不带“+”前缀的电话号码)。
    • context.id 是 WhatsApp 平台上的原始消息 ID,以 wamid. 开头。

接收互动按钮回复消息

在这种情况下,您的 Webhook 端点收到了一条接收互动按钮回复消息:
  • interactive 字段包含用户在您之前发送的互动消息中点击的按钮回复。
  • context 字段包含您之前向用户发送的互动消息的相关信息。
example-inboundmessage-buttonreply.png

请求

响应

在持久化接收事件后确认送达。

说明

  • context 包含您之前发送的互动消息的相关信息。
    • context.from 是发送该互动消息者的 WhatsApp ID(不带“+”前缀的电话号码)。
    • context.id 是 WhatsApp 平台上的原始消息 ID,以 wamid. 开头。

接收互动 Flow 响应消息

Flow 完成后,系统将向 WhatsApp 聊天发送一条响应消息。您将像接收来自用户的所有其他消息一样接收它——通过消息 Webhook。response_json 字段将包含特定于 Flow 的数据。

请求

响应

在持久化接收事件后确认送达。

说明

  • interactive.type 始终为 nfm_reply。interactive.name 始终为 flow。interactive.body 始终为 Sent。
  • interactive.response_json 是特定于 Flow 的数据。其结构要么在 Flow JSON 中定义(参见 Complete 操作),要么(如果 Flow 正在使用端点)由端点控制(参见 数据交换请求 中的 Final Response Payload)。将 interactive.response_json JSON 字符串解析为 JSON 对象,其值的数据类型可以各不相同。通常情况下,这些值是纯文本,除以下情况外:
    • 当它来自 CheckboxGroup 组件时,该值是一个字符串列表。
    • 当它来自 OptIn 组件时,该值为布尔值,即 true 或 false。目前,如果存在,该值必须为 true,因为如果用户未选择加入,response_json 中将不会包含此类键。
    • 当它来自 DatePicker 组件时,该值是表示 Unix 时间戳(毫秒)的字符串,例如 "1725936737548"(即 2024-09-10T02:52:17.548Z)。自 Flow JSON 版本 5.0 起,日期将设置为 “yyyy-MM-dd” 格式,这使得这些值与时区无关。
  • 要发送带有 Flow 的消息,请参阅 Flow 消息模板和 交互式 Flow 消息。

入站系统消息

在此情况下,您的 Webhook 端点接收到了入站系统消息:
  • type 设置为 system,且 system.type 设置为 user_changed_number。
  • 用户在 WhatsApp 上更改了其电话号码,wa_id 是新的 WhatsApp ID(不带 + 前缀的电话号码)。
  • user_id 是新的 BSUID。在 Meta 提供时,previous_user_id 用于标识先前的 BSUID。
  • parent_user_id 和 previous_parent_user_id 是可选的父级 BSUID,仅在启用且由 Meta 提供时才会包含。请保留 system 中原始的 snake_case 字段名称。

请求

响应

持久化接收事件后确认交付。

说明

按 type 路由事件,按 id 进行去重,并将缓慢或容易失败的工作转移到异步处理器。

入站 BSUID 变更消息

您还可以接收 system.type 设置为 user_changed_user_id 的入站系统消息。用户的电话号码可能保持不变或不可用。当两者均提供时,使用 system.previous_user_id 和 system.user_id 关联先前和新的 BSUID。父级 BSUID 字段为可选。

请求

响应

持久化接收事件后确认交付。

说明

此示例省略了 from 和 system.wa_id,因为电话号码不可用。如果提供了 wa_id,它包含不带前导 + 的电话号码;不要假定它与先前的电话号码不同。当事件未提供替换项时,请保留现有电话号码。

入站订单消息

在此情况下,当客户将一种或多种商品添加到购物车并提交订单时,您的 Webhook 端点接收到了入站订单消息:
  • 包含已订购商品的信息。

请求

响应

持久化接收事件后确认交付。

说明

按 type 路由事件,按 id 进行去重,并将缓慢或容易失败的工作转移到异步处理器。

入站商品咨询消息

在此情况下,当客户咨询商品时,您的 Webhook 端点接收到了入站文本消息:
  • 包含有关商品的信息。

请求

响应

持久化接收事件后确认交付。

说明

  • 当用户询问特定商品的更多信息时,会收到商品咨询消息。可以在两种情况下收到此类消息:
    • 当客户回复 单商品或多商品消息 时。
    • 当客户通过其他入口点访问商家目录,导航至商品详情页面,并点击“就此商品向商家发消息”时。

入站请求欢迎消息

每当 WhatsApp 用户首次与您发起聊天时,您都可以通过 Webhook 收到通知。如果您想回复这些用户由您自行设计的特殊欢迎消息,这会非常有用。 如果您启用此功能且用户发起了聊天(通常是当用户点击 通用链接,即 wa.me 或 api.whatsapp.com 链接),WhatsApp 客户端会检查该用户与您的商业电话号码之间是否存在现有的消息会话。如果不存在,客户端会触发 request_welcome Webhook。然后,您可以使用自己的欢迎消息回复该用户。 example-inboundmessage-welcomemessage

请求

响应

持久化接收事件后确认交付。

说明

  • 要为电话号码启用此功能,请导航至 Meta WhatsApp 管理工具 > 电话号码 > 设置 > 自动化。
  • 要测试 request_welcome 消息,如果您与该商业电话号码已有正在进行的聊天会话,您必须先删除该聊天。
  • 此功能仅触发入站 request_welcome 消息,不会自动回复任何消息。是否回复欢迎消息由您决定。

入站 SMS

当用户回复您的 SMS 时,使用 sms.inbound.received。

请求

响应

持久化接收事件后确认交付。

说明

从 smsInbound.text 读取回复。from 是用户的电话号码,to 是您已注册的 Sender ID,sendTime 是消息发送时间。切勿将此事件解析为 whatsappInboundMessage。

WhatsApp 营销偏好设置

当 WhatsApp 用户停止或恢复接收营销消息时,请使用 whatsapp.user.preferences。

请求

响应

在持久化接收该事件后确认投递。

说明

从 whatsappUserPreference 中读取 category 和 value;此示例记录了一项停止接收营销消息的请求。使用商业标识符和提供的客户标识符来匹配该偏好设置。未启用父级 BSUID 时会省略 parentUserId。保留 detail 作为说明文本,并保留提供的 timestamp。这是专用的偏好设置事件,不是入站聊天消息或 contact.unsubscribe.created 载荷。

Messenger 入站文本

订阅 messenger.inbound_message.received 以接收普通的一对一文本消息。在接受事件之前验证 YCloud-Signature 标头。投递重试会保留 Event.id;从相同来源事实重新创建事件可能会生成新的 Event.id。通过 messengerInboundMessage.id 关联重复的入站消息。

请求

响应

说明

客户 PSID 为 from,Facebook Page ID 为 to。请原样保留文本,包括空格。sendTime 是保存的源事件时间;createTime 是本地持久化时间。此事件仅包含普通文本消息。源端重复投递可能会针对相同的已保存消息 ID 创建另一个事件。

Messenger 入站文本编辑

订阅 messenger.inbound_message.updated 以接收现有入站消息的最新文本。在处理载荷之前验证 YCloud-Signature。

请求

响应

说明

更新记录时,请保留相同的消息 id 和 metaMessageId。新的 text.body、累计 editCount 和 editTime 用于描述已保存的编辑。消息 sendTime 和 createTime 保留其原始值;事件 createTime 为编辑时间。未经编辑的消息会省略编辑字段。仅更新现有的入站消息;不会重建缺失的原始消息和被取代的编辑版本。投递重试会保留事件 ID,但源端重新处理可能会生成新的事件 ID。使用消息 ID 和编辑计数来处理重复与排序。