WhatsApp Business App 已发送消息同步 Webhook 示例

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

概述

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

准备工作

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

工作原理

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

请求

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

响应

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

HTTP/1.1 200 OK

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

出站文本消息

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

请求

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/1.1 200 OK

说明

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

出站图片消息

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

包含之前发送的图片。

请求

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/1.1 200 OK

说明

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

出站视频消息

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

包含之前发送的视频。

请求

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/1.1 200 OK

说明

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

出站音频消息

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

包含之前发送的音频。

请求

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/1.1 200 OK

说明

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

出站文档消息

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

包含之前发送的文档。

请求

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/1.1 200 OK

说明

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

Business App 消息已创建

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

请求

{
  "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/1.1 200 OK

说明

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

开始使用

指南

接口

Webhooks

WhatsApp Business App 已发送消息同步 Webhook 示例

概述

准备工作

工作原理

请求

响应

出站文本消息

请求

响应

说明

出站图片消息

请求

响应

说明

出站视频消息

请求

响应

说明

出站音频消息

请求

响应

说明

出站文档消息

请求

响应

说明

Business App 消息已创建

请求

响应

说明

​概述

​准备工作

​工作原理

​请求

​响应

​出站文本消息

​请求

​响应

​说明

​出站图片消息

​请求

​响应

​说明

​出站视频消息

​请求

​响应

​说明

​

​出站音频消息

​请求

​响应

​说明

​出站文档消息

​请求

​响应

​说明

​Business App 消息已创建

​请求

​响应

​说明

概述

准备工作

工作原理

请求

响应

出站文本消息

请求

响应

说明

出站图片消息

请求

响应

说明

出站视频消息

请求

响应

说明

出站音频消息

请求

响应

说明

出站文档消息

请求

响应

说明

Business App 消息已创建

请求

响应

说明