> ## 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 衍生的完整目录，请参阅[所有示例](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。

## 概述

处理 WhatsApp Business App 已发送消息同步事件。

## 准备工作

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

## 工作原理

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

## 请求

以下场景展示了发送到您的 Webhook URL 的请求。将事件 `id` 视为传递标识符，并使用 `type` 路由有效负载。

## 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

> [!NOTE]
>
> 有关端点设置、签名验证和重试机制，请参阅[配置 Webhook](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

## 出站文本消息

在此情况下，您的 Webhook 端点收到了商业客户通过 WhatsApp Business app 或支持的配套设备向 WhatsApp 用户发送的出站文本消息：

从 `whatsappMessage.text.body` 读取发送的文本。

### 请求

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_example_smb_echoes",
  "type": "whatsapp.smb.message.echoes",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "username": "example_customer"
    }
  }
}'
```

### 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

通过 `type` 路由事件，通过 `id` 进行去重，并将耗时或易失败的任务转至异步处理器处理。

## 出站图片消息

在此情况下，您的 Webhook 端点收到了商业客户通过 WhatsApp Business app 或支持的配套设备向 WhatsApp 用户发送的出站图片消息：

* 包含之前发送的图片。

### 请求

```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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'
```

### 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## 出站视频消息

在此情况下，您的 Webhook 端点收到了商业客户通过 WhatsApp Business app 或支持的配套设备向 WhatsApp 用户发送的出站视频消息：

* 包含之前发送的视频。

### 请求

```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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "video/mp4"
    }
  }
}'
```

### 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

##

## 出站音频消息

在此情况下，您的 Webhook 端点收到了商业客户通过 WhatsApp Business app 或支持的配套设备向 WhatsApp 用户发送的出站音频消息：

* 包含之前发送的音频。

### 请求

```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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "audio/ogg; codecs=opus"
    }
  }
}'
```

### 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## 出站文档消息

在此情况下，您的 Webhook 端点收到了商业客户通过 WhatsApp Business app 或支持的配套设备向 WhatsApp 用户发送的出站文档消息：

* 包含之前发送的文档。

### 请求

```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.message.echoes",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "sent",
    "from": "BUSINESS-PHONE-NUMBER",
    "to": "CUSTOMER-PHONE-NUMBER",
    "toUserId": "US.13491208655302741918",
    "toParentUserId": "US.1181579921288684483",
    "customerProfile": {
      "username": "@joee"
    },
    "wabaId": "WABA-ID",
    "createTime": "2022-03-01T12:00:00.000Z",
    "sendTime": "2022-03-01T12:00:01.000Z",
    "bizType": "whatsapp",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/5926236...",
      "id": "592623615738103",
      "caption": "图片",
      "sha256": "LeRpQJq/h4HTjm...",
      "mime_type": "image/jpeg"
    }
  }
}'
```

### 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

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

## Business App 消息已创建

当 WhatsApp Business App 消息发送时，使用 `whatsapp.smb.message.created`。

### 请求

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_example_smb_created",
  "type": "whatsapp.smb.message.created",
  "apiVersion": "v2",
  "createTime": "2026-10-09T08:00:00.000Z",
  "whatsappMessage": {
    "id": "MESSAGE_ID",
    "wamid": "wamid.EXAMPLE",
    "wabaId": "WABA_ID",
    "from": "+16315551111",
    "to": "+16315552222",
    "type": "text",
    "text": {
      "body": "Your order is ready for pickup."
    },
    "status": "sent",
    "createTime": "2026-10-08T12:00:00.000Z",
    "sendTime": "2026-10-08T12:00:00.000Z"
  }
}
```

### 响应

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### 说明

从 `whatsappMessage` 读取出站消息。其 `type` 用于选择内容对象；此文本示例使用 `text.body`。将此事件与 `whatsapp.smb.message.echoes` 分开路由，同时在适当时共享消息解析逻辑。这些属于 Business App 共存事件，而非 Meta Business Agent 回显事件。


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