功能简介
YCloud 的 WhatsApp 通话 API 用于管理 WhatsApp 用户与商业电话号码之间的语音通话信令。您的应用程序通过 YCloud 交换 SDP,而您的 WebRTC 实现则负责处理音频连接。 通话可以从任一方向发起:- 用户发起: WhatsApp 用户致电您的企业。您的应用程序接收 Offer 并接听或拒接通话。
- 企业发起: 您的应用程序创建 Offer 并请求 YCloud 致电 WhatsApp 用户。
通话 API 处理通话信令,而非 WebRTC 媒体栈。您的应用程序负责对等连接设置、音频采集与播放、SDP 生成以及 WebRTC 资源清理。
API 全景图
通话 API 与 Webhook 事件遵循相同的生命周期,但并不构成适用于每次通话的单一顺序。完成通用设置后,按照用户发起或企业发起的流程进行操作。使用通话 ID(wacid)来关联每个操作和事件。
通用设置
用户发起的通话
企业发起的通话
通用通话结束流程
可选媒体处理
这些表格描述了应用程序工作流。它们并不保证 Webhook 的传送顺序与行顺序一致。请通过
wacid 关联事件并以幂等方式处理重复投递。
准备工作
在发起通话请求之前,请准备以下内容:- YCloud 账户 API 密钥。在
X-API-Key请求头中发送它。参见身份验证。 - 在 YCloud 注册的 WhatsApp 商业账户和商业电话号码。
- 为该电话号码启用了通话功能。
- 能够创建和应用 SDP Offer 及 Answer 的 WebRTC 音频实现。
- 订阅了集成所用通话事件的 YCloud Webhook 端点。参见配置 Webhook。
- 企业发起通话所需的用户呼叫权限(当需要时)。
工作原理
首先配置商业电话号码。然后根据通话方向交换 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 会尝试分别保存每个部分。如果任一部分保存失败,另一部分可能已存储。出错后请读取这两项设置,然后仅重试仍需更新的部分。
处理用户发起的通话
在用户发起的通话中,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
whatsapp.call.terminate 获取最终通话结果。
文档记录的呼入接听窗口期约为收到 connect Webhook 后的 30–60 秒。请及时接听;未接听的通话将在用户端以 Not Answered 通知结束,并触发 terminate Webhook。
即使 WebRTC 连接已建立,也只能在接听请求返回 HTTP 200 后才开始传输音频。开始过早可能会截断前几个词;开始过晚则会导致静音。
拒绝而非接听
如果客服人员无法接听呼入电话,请拒绝该通话,而不是创建活动会话。 端点:POST /whatsapp/calls/reject
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
响应
所有五个信令端点均返回相同的响应结构:wacid 标识与操作关联的通话。success: true 确认信令操作成功;这并不确认另一方参与者已接听或通话已完成。请通过 WebRTC 状态和呼叫 Webhook 事件来获取这些结果。
处理最终通话事件
whatsapp.call.terminate 是通话的终止生命周期事件。
收到此事件时,请结束通话记录并释放所有剩余的 WebRTC 资源。先前的 API 响应并不确认通话已完成。
接收录音和转录
启用捕获后,媒体处理将在通话生命周期结束后继续进行。录音和转录具有独立的终止事件:
以下示例展示了一个可用的录音:
下载可用资产
仅在相应事件报告AVAILABLE 之后才调用媒体端点。
端点: GET /whatsapp/calls/media/{mediaAssetId}
.ogg;转录使用 .json。
只有所属的 YCloud 租户可以下载资产。资产从创建之时起保留 30 天。丢失、不可用、过期或无权拥有的资产将返回 HTTP 404。
构建可靠的 Webhook 接收器
将您的端点订阅到集成所需的事件:- 在信任事件之前,保留原始请求体并验证
YCloud-Signature。 - 持久化存储事件或加入持久化任务队列。
- 及时返回成功的
2xx响应。 - 根据顶级事件
id进行去重。 - 通过
wacid关联通话数据;保留phoneId以备后续操作使用。 - 处理相隔极短时间到达的相关事件,并容忍重复投递。
处理错误与恢复
通话端点使用 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 事件示例。

