跳转到主要内容

功能简介

YCloud 的 WhatsApp 通话 API 用于管理 WhatsApp 用户与商业电话号码之间的语音通话信令。您的应用程序通过 YCloud 交换 SDP,而您的 WebRTC 实现则负责处理音频连接。 通话可以从任一方向发起:
  • 用户发起: WhatsApp 用户致电您的企业。您的应用程序接收 Offer 并接听或拒接通话。
  • 企业发起: 您的应用程序创建 Offer 并请求 YCloud 致电 WhatsApp 用户。
通话 API 处理通话信令,而非 WebRTC 媒体栈。您的应用程序负责对等连接设置、音频采集与播放、SDP 生成以及 WebRTC 资源清理。

API 全景图

通话 API 与 Webhook 事件遵循相同的生命周期,但并不构成适用于每次通话的单一顺序。完成通用设置后,按照用户发起或企业发起的流程进行操作。使用通话 ID(wacid)来关联每个操作和事件。

通用设置

用户发起的通话

企业发起的通话

通用通话结束流程

可选媒体处理

这些表格描述了应用程序工作流。它们并不保证 Webhook 的传送顺序与行顺序一致。请通过 wacid 关联事件并以幂等方式处理重复投递。

准备工作

在发起通话请求之前,请准备以下内容:
  1. YCloud 账户 API 密钥。在 X-API-Key 请求头中发送它。参见身份验证。
  2. 在 YCloud 注册的 WhatsApp 商业账户和商业电话号码。
  3. 为该电话号码启用了通话功能。
  4. 能够创建和应用 SDP Offer 及 Answer 的 WebRTC 音频实现。
  5. 订阅了集成所用通话事件的 YCloud Webhook 端点。参见配置 Webhook。
  6. 企业发起通话所需的用户呼叫权限(当需要时)。
请联系您的 YCloud 客户代表以开通 Calling API 访问权限。有关出站资格,请遵循当前 Calling 要求,包括商业资产组合(Business Portfolio)2,000 个客户的消息传递层级以及支持的商业号码国家/地区。原有的 1,000 次会话门槛已被当前要求取代。 以下示例使用这些环境变量:
请将 API Key 保留在您的服务器上。不要将其放入浏览器或移动应用程序代码中。

工作原理

首先配置商业电话号码。然后根据通话方向交换 SDP。API 响应会确认单个信令操作,而 Webhook 事件则报告状态更改和最终结果。如果启用了捕获功能,单独的事件会提示录音或转录文本何时可供下载。

请求

配置商业电话号码

通话和捕获设置从属于特定的 WhatsApp 商业电话号码。在处理通话之前请先进行配置。

读取 Calling 设置

使用 GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings 检查是否已启用 Calling 以及 Calling 图标是否可见:
如果省略 type,YCloud 会返回 Calling 设置响应。

启用 Calling

在开始接听或拨打电话之前,请使用 POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings 保存 Calling 设置:
响应包含已保存的 calling 对象。在处理实时通话之前,请完成 Webhook 和 WebRTC 会话的配置。

配置录音和转录

捕获设置适用于通过 API 发起的新通话。您可以启用录音、转录或两者同时启用。
要读取捕获设置,请使用 type=capture:
您可以在同一个 POST 请求中包含 calling 和 capture。验证电话号码的访问权限后,YCloud 会尝试分别保存每个部分。如果任一部分保存失败,另一部分可能已存储。出错后请读取这两项设置,然后仅重试仍需更新的部分。

处理用户发起的通话

用户发起 Calling 流程 在用户发起的通话中,WhatsApp 会发送 SDP offer。您的应用程序应答该 offer,然后接听或拒绝该通话。

1. 接收 connect 事件

订阅 whatsapp.call.connect。用户发起的事件其 direction 会设置为 USER_INITIATED,并包含 SDP offer。
将 callingConnect.wacid 和 callingConnect.phoneId 保存在一起。将收到的 SDP offer 应用到您的 WebRTC peer connection,并创建 SDP answer。

2. 预先接听通话(Pre-accept)

在创建 SDP answer 之后、坐席接听通话之前调用 pre-accept。这会准备好媒体通道,并可减少通话接通时的音频截断问题。 端点: POST /whatsapp/calls/preAccept
预接听成功后,请将通话保持在振铃或就绪状态。预接听不会代表用户接听电话。

3. 接听通话

客服人员接听时,向接听端点发送相同的 phoneId、wacid、SDP 类型和 SDP 应答。 端点: POST /whatsapp/calls/accept
请求字段和响应格式与预接听相同。收到成功响应后,利用 WebRTC 连接状态判断媒体就绪情况,并等待 whatsapp.call.terminate 获取最终通话结果。 文档记录的呼入接听窗口期约为收到 connect Webhook 后的 30–60 秒。请及时接听;未接听的通话将在用户端以 Not Answered 通知结束,并触发 terminate Webhook。 即使 WebRTC 连接已建立,也只能在接听请求返回 HTTP 200 后才开始传输音频。开始过早可能会截断前几个词;开始过晚则会导致静音。

拒绝而非接听

如果客服人员无法接听呼入电话,请拒绝该通话,而不是创建活动会话。 端点: POST /whatsapp/calls/reject
响应采用标准 Calling 响应。请求后释放本地 PeerConnection,并在该 wacid 随后传来终止事件时仍接受该事件。

发起企业外呼通话

在企业发起的通话中,您的应用程序会创建 SDP offer 并将其发送至 YCloud。

获取通话权限

在发起通话前,需先获得用户的通话权限。可在有效的客户服务窗口期内发送交互式权限请求:
将此请求体发送至 POST /v2/whatsapp/messages/sendDirectly 或使用 POST /v2/whatsapp/messages 加入队列。 您也可以创建通话权限模板。例如,将此请求体提交至 POST /v2/whatsapp/templates,然后等待审核批准:
发送已获批的模板及其正文参数:
在电话号码的通话设置中启用 callback_permission_status 时,用户发起的呼叫可以授予回拨权限。用户也可以直接在商业主页中授予永久通话权限。 权限回复以 whatsapp.inbound_message.received 事件形式送达。请检查 interactive.call_permission_reply 对象,而不仅仅检查权限请求消息是否送达:
被拒绝或权限过期后,切勿发起通话。Meta 错误 138006 表示该商业号码未获得所需的通话权限。有关提供商的错误详情,请参见 Meta 的 Calling 错误。

1. 创建 SDP offer

创建本地 WebRTC PeerConnection 并附加音频轨道。生成 SDP offer,将其设置为本地描述(local description),并在将 offer 发送给 YCloud 之前等待该操作完成。

2. 连接通话

端点: POST /whatsapp/calls/connect 至少提供 to 或 recipient 之一。如果两者均发送,YCloud 将使用 to 并忽略 recipient。
请立即存储返回的 wacid。success: true 仅表示连接操作已受理,并不代表用户已接听。

3. 应用应答并跟踪通话尝试

YCloud 会为该通话发送 whatsapp.call.connect。对于商家发起的呼叫,该事件包含 direction: BUSINESS_INITIATED 并携带远端 SDP answer。将该应答作为同一对等连接的远端描述应用。 订阅 whatsapp.call.status.updated 以跟踪该呼叫尝试:
请确保事件处理具备幂等性,以便在重新投递时不会重复执行客服操作、计费或清理工作。

终止进行中的通话

当您的应用程序需要结束进行中的呼入或呼出通话时,请调用 terminate。 端点: POST /whatsapp/calls/terminate
请求字段与 reject 请求一致。成功的响应仅确认 YCloud 已处理终止操作。请保持通话记录开启,直到收到最终的终止事件或您自己的恢复策略将其关闭。

响应

所有五个信令端点均返回相同的响应结构:
wacid 标识与操作关联的通话。success: true 确认信令操作成功;这并不确认另一方参与者已接听或通话已完成。请通过 WebRTC 状态和呼叫 Webhook 事件来获取这些结果。

处理最终通话事件

whatsapp.call.terminate 是通话的终止生命周期事件。
收到此事件时,请结束通话记录并释放所有剩余的 WebRTC 资源。先前的 API 响应并不确认通话已完成。

接收录音和转录

启用捕获后,媒体处理将在通话生命周期结束后继续进行。录音和转录具有独立的终止事件: 以下示例展示了一个可用的录音:
两个负载属性使用相同的字段:

下载可用资产

仅在相应事件报告 AVAILABLE 之后才调用媒体端点。 端点: GET /whatsapp/calls/media/{mediaAssetId}
该端点将完整文件作为附件返回,不支持字节范围下载。录音使用 .ogg;转录使用 .json。 只有所属的 YCloud 租户可以下载资产。资产从创建之时起保留 30 天。丢失、不可用、过期或无权拥有的资产将返回 HTTP 404。

构建可靠的 Webhook 接收器

将您的端点订阅到集成所需的事件:
对于每个请求:
  1. 在信任事件之前,保留原始请求体并验证 YCloud-Signature。
  2. 持久化存储事件或加入持久化任务队列。
  3. 及时返回成功的 2xx 响应。
  4. 根据顶级事件 id 进行去重。
  5. 通过 wacid 关联通话数据;保留 phoneId 以备后续操作使用。
  6. 处理相隔极短时间到达的相关事件,并容忍重复投递。
有关端点创建、签名验证和投递行为,请参阅 配置 Webhook。Webhook 有效负载示例 页面包含完整的生成示例。

处理错误与恢复

通话端点使用 YCloud 的标准 API 错误响应。有关响应结构和重试指导,请参阅 处理错误。 使用以下检查项排查常见的通话失败问题: 请求超时并不代表信令操作已经失败。在重试之前,请结合 Webhook 事件与当前的本地通话状态对请求进行对账核对。该操作可能已经送达 WhatsApp。

接入清单

  • 在正确的商业电话号码上启用通话功能。
  • 配置并测试所有必需的通话 Webhook 订阅。
  • 验证 Webhook 签名并对事件进行去重。
  • 将 wacid、phoneId、通话方向和当前状态一并存储。
  • 将 API success 视为操作已被受理,而非最终通话结果。
  • 仅将 preAccept 用作准备阶段;调用 accept 来应答。
  • 根据 whatsapp.call.terminate 完成通话收尾处理。
  • 仅在收到 AVAILABLE 事件后并在 30 天内下载录制的媒体文件。
  • 在呼叫被拒绝、终止、失败以及本地超时时释放 WebRTC 资源。
  • 避免在常规应用程序日志中记录 API Key、完整 SDP 或参与方标识符。

Calling API 参考

查看每个 Calling 端点的详细请求和响应架构。

Webhook 有效负载示例

查看根据 Webhook 规范生成的完整 Calling 事件示例。