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 用户发送的出站文本消息：:

包含之前发送的纯文本内容。
在 context 中包含所提及的消息信息。

请求

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

说明

按 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 天内下载此文件。

开始使用

指南

接口

Webhooks

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

功能说明

准备工作

工作原理

请求

响应

出站文本消息

请求

响应

说明

出站图片消息

请求

响应

说明

出站视频消息

请求

响应

说明

出站音频消息

请求

响应

说明

出站文档消息

请求

响应

说明

​功能说明

​准备工作

​工作原理

​请求

​响应

​出站文本消息

​请求

​响应

​说明

​出站图片消息

​请求

​响应

​说明

​出站视频消息

​请求

​响应

​说明

​

​出站音频消息

​请求

​响应

​说明

​出站文档消息

​请求

​响应

​说明

功能说明

准备工作

工作原理

请求

响应

出站文本消息

请求

响应

说明

出站图片消息

请求

响应

说明

出站视频消息

请求

响应

说明

出站音频消息

请求

响应

说明

出站文档消息

请求

响应

说明