WhatsApp 通话结束与捕获 Webhook 示例

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

功能概述

处理 WhatsApp 通话结束、录音以及转录事件。

准备工作

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

工作原理

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

请求

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

响应

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

HTTP/1.1 200 OK

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

商家或 WhatsApp 用户均可随时终止通话。当商家或 WhatsApp 用户终止通话时，您会收到 Call Terminate Webhook：

通话已完成

请求

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

响应

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

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或易出错的操作移至异步处理器。

通话失败

请求

{
  "id": "evt_675907f431c55113a751d0e7",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-11T03:33:08.679Z",
  "callingTerminate": {
    "id": "675907a13ae4a901f05fee95",
    "wacid": "wacid.HBgNODYxNTE1NzEzNzYyM",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733826484000,
    "endTime": 1733826637000,
    "duration": 30,
    "status": "FAILED",
    "errorCode": "131000"
  }
}

响应

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

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 进行去重，并将耗时或易出错的操作移至异步处理器。

通话录音可用

对于启用了录音功能的 API 发起通话，whatsapp.call.recording.updated 会报告录音是否可用或是否发生永久性处理失败。

请求

{
  "id": "evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z",
  "type": "whatsapp.call.recording.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:00:00.000Z",
  "callingRecording": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0c2e4b05c2d8f1a3b47",
    "status": "AVAILABLE"
  }
}

响应

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

HTTP/1.1 200 OK

说明

使用 callingRecording.wacid 标识通话，使用 phoneId 标识商业电话号码。仅在 status 为 AVAILABLE 时下载 mediaAssetId。录音处理独立于通话结束结果。对于 FAILED，请检查 error.code 和 error.retryable。请参阅录音与转录。

通话转录失败

对于启用了转录功能的 API 发起通话，whatsapp.call.transcription.updated 会报告转录是否可用或是否发生永久性处理失败。

请求

{
  "id": "evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:01:00.000Z",
  "callingTranscription": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0d9e4b05c2d8f1a3b48",
    "status": "FAILED",
    "error": {
      "code": "CALLING_TRANSCRIPTION_PROCESSING_FAILED",
      "retryable": false
    }
  }
}

响应

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

HTTP/1.1 200 OK

说明

请读取 callingTranscription 而不是 callingRecording。在此示例中，status 为 FAILED 且 error.retryable 为 false。请勿尝试下载失败的资源。AVAILABLE 结果使用 mediaAssetId 进行下载；转录结果独立于录音结果和通话结束状态。

开始使用

指南

接口

Webhooks

WhatsApp 通话结束与捕获 Webhook 示例

功能概述

准备工作

工作原理

请求

响应

通话已完成

请求

响应

说明

通话失败

请求

响应

说明

通话录音可用

请求

响应

说明

通话转录失败

请求

响应

说明

​功能概述

​准备工作

​工作原理

​请求

​响应

​通话已完成

​请求

​响应

​说明

​通话失败

​请求

​响应

​说明

​通话录音可用

​请求

​响应

​说明

​通话转录失败

​请求

​响应

​说明

功能概述

准备工作

工作原理

请求

响应

通话已完成

请求

响应

说明

通话失败

请求

响应

说明

通话录音可用

请求

响应

说明

通话转录失败

请求

响应

说明