> ## 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 Business App 历史消息 Webhook 示例

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

<Note>如需查看基于 Schema 生成的完整目录，请参阅[所有示例](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。</Note>

## 功能简介

处理 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>有关端点设置、签名验证和重试机制的更多信息，请参阅[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。</Note>

## 入站文本消息

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

* 包含用户发送的纯文本内容。
* 在 `context` 中包含被引用消息的信息。
* 其他类型的消息可参考 [whatsappInboundMessage](/zh/api-reference/guides/examples/webhook-examples/whatsapp-inbound-message-webhook-examples)

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 示例](/zh/api-reference/guides/examples/webhook-examples/whatsapp-business-app-sent-message-sync-webhook-examples)

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## 仅进度历史数据块

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

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.