WhatsApp Business App 历史消息 Webhook 示例

如需查看基于 Schema 生成的完整目录，请参阅所有示例。

功能简介

处理 WhatsApp Business App 历史同步事件。

准备工作

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

工作原理

事件发生时，YCloud 会发送 HTTP POST 请求。请验证签名、持久化记录事件、返回 2xx 响应，并异步处理耗时操作。对于由 Meta 历史数据块（chunk）创建的事件，YCloud 会将该数据块的 phase 和 progress 复制到顶层事件中。包含消息的数据块会附带一个特定方向的消息对象。如果 threads 和 errors 均为空，YCloud 将发送一个不包含 whatsappMessage 或 whatsappInboundMessage 的仅进度事件。投递采用至少一次机制，且可能乱序到达。请根据事件 id 进行去重；请勿使用 phase 和 progress 作为唯一定位投递的键。

请求

以下场景展示了投递至您 Webhook URL 的请求。请将事件 id 视为投递标识符，并使用 type 对载荷进行路由。

响应

接收事件后返回 2xx 状态码。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制的更多信息，请参阅配置 Webhook。

入站文本消息

在此场景中，您的 Webhook 端点收到了一条入站文本消息：

包含用户发送的纯文本内容。
在 context 中包含被引用消息的信息。
其他类型的消息可参考 whatsappInboundMessage

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId": "US.13491208655302741918",
    "fromParentUserId": "US.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeWick"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'

响应

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

HTTP/1.1 200 OK

说明

入站消息是指客户发送到您商业电话号码的消息。
context（可选）包含被引用消息的信息，通常用于回复用户或企业之前发送的消息。
- context.from 是发送被引用消息的用户的 WhatsApp ID（不带“+”前缀的电话号码）。
- context.id 是被引用消息在 WhatsApp 平台上的原始 ID，以 wamid. 开头。

出站文本消息

在此场景中，您的 Webhook 端点收到了一条由商业客户通过 WhatsApp Business app 或支持的配套设备发送给 WhatsApp 用户的出站文本消息：

包含之前发送的纯文本内容。
在 context 中包含被引用消息的信息。
其他类型的消息可参考 WhatsApp Business App 已发送消息同步 Webhook 示例

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "phase": 1,
  "progress": 40,
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId" : "US.13491208655302741918",
    "toParentUserId": "US.11815799212886844830",
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "text",
    "text": {
      "body": "Hi there! How can we help?"
    },
    "context": {
      "message_id": "wamid.BgNODYxN..."
    }
  }
}'

响应

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

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或容易失败的操作转移到异步处理器。

仅进度历史数据块

当 Meta 历史数据块既不包含会话线程也不包含错误时，事件仍会报告其同步元数据。该事件不包含消息载荷。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_progressOnly73",
  "type": "whatsapp.smb.history",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:02.000Z",
  "phase": 1,
  "progress": 73
}'

响应

HTTP/1.1 200 OK

说明

此事件特意不包含 WhatsApp 消息对象。请继续跟踪进度，并像处理其他 Webhook 投递一样对其进行确认。

开始使用

指南

接口

Webhooks

WhatsApp Business App 历史消息 Webhook 示例

功能简介

准备工作

工作原理

请求

响应

入站文本消息

请求

响应

说明

出站文本消息

请求

响应

说明

仅进度历史数据块

请求

响应

说明

​功能简介

​准备工作

​工作原理

​请求

​响应

​入站文本消息

​请求

​响应

​说明

​出站文本消息

​请求

​响应

​说明

​仅进度历史数据块

​请求

​响应

​说明

功能简介

准备工作

工作原理

请求

响应

入站文本消息

请求

响应

说明

出站文本消息

请求

响应

说明

仅进度历史数据块

请求

响应

说明