从 WhatsApp 聊天到人工通话：UnifyPort 语音与视频通话内测

客户已经在 WhatsApp 里描述了问题，但再发一段文字也未必说得更清楚。客服可能需要直接确认配送安排，或者通过摄像头看一下产品故障。UnifyPort 新增的通话内测能力，让业务系统可以准备 WhatsApp 单聊语音或视频通话，由客服在浏览器中发起，再通过 Webhook 把通话状态接回后端。

当前范围是 WhatsApp 人工发起的呼出通话。内测资格按工作区开通，需要联系技术支持申请；仅创建 API Key 不会自动获得通话权限，本次内测也尚未开放呼入。

通话内测新增了什么

通话 API 文档已经提供三个操作：

• POST /v1/calls：准备语音或视频通话，返回短期有效的一次性 join_url。
• GET /v1/calls/active：查询指定账号当前由 UnifyPort 管理的通话。
• POST /v1/calls/{call_id}/hangup：结束指定通话。

两个 Webhook 事件帮助业务系统跟进状态：call.answered 表示通话接通，call.ended 表示通话结束，并提供结束原因和接通时长。开发者可以用这些接口和事件，为已有客服流程增加一个人工通话步骤。

创建 API 只负责准备通话。客服打开返回的链接，并点击 Start call 后才拨号。 在业务界面中明确展示这个动作，让客服在发起前核对选中的客户。

什么时候需要从文字沟通转入通话

可以考虑下面几个假设的客服场景：

• 订单确认：配送安排在几轮短消息中越说越复杂，客服与客户通过语音逐项确认。
• 售后排障：客服通过语音引导客户，按顺序完成检查。
• 视频辅助：客户通过视频展示产品或安装问题，方便双方交流。

这些是可以设计的应用流程，并非已经验证的客户案例或效果数据。团队仍需决定何时发起通话，并在自己的客服系统中记录后续动作。

共享收件箱可以在选中的 WhatsApp 聊天旁提供通话入口。使用当前消息账号下这段聊天的 conversation_id，通话接口不接受任意手机号字符串。分配与解决状态继续由业务系统维护，相关设计可以参考 WhatsApp 共享收件箱指南。

先准备通话，再由客服在浏览器中发起

首先申请工作区内测资格，并连接一个已经完成授权的 WhatsApp 消息账号。如果还在处理账号接入，可以先阅读 QR 与 Passkey 授权指南，完成这一独立的准备步骤。

由后端使用工作区的 X-Api-Key 发送创建请求。下面的 JSON 用于说明实际请求结构；提交到 POST /v1/calls 前，将 acc_example 和 <conversation_id> 替换为选中的账号及其真实会话标识：

{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}

语音使用 voice，支持视频的通话使用 video。API Key 保存在服务端，返回的 join_url 只私下交给本次通话的客服。

创建成功返回 201 Created，包含 call_id、state: preparing、join_url 和 expires_at。这个结果还不能证明已经向客户拨号，也不能证明客户接听了。

准备期从创建起默认 2 分钟。服务端可以调整期限，因此实际截止时间以返回的 expires_at 为准。客服必须在到期前打开链接并点击 Start call；这个准备期限不限制已经接通的通话时长。

浏览器必须获得麦克风权限，摄像头权限可选。一次性链接需要保密，不要公开，也不要在日志中记录完整 URL。

把通话状态接回客服流程

在自己的系统中，将返回的 call_id 与选中的账号、会话和客服任务关联保存。需要时可以通过查询当前通话接口找回系统管理的通话，包括遗失标识的情况。没有当前通话时返回 data: {}；它无法判断账号或客户是否正在 WhatsApp 手机端通话。

订阅 call.answered 和 call.ended，更新业务系统中的通话记录。如果 subscribed_events 使用具体事件列表，需要包含这两个事件名；内测工作区使用 *、空数组或省略列表时，也会包含有权接收的通话事件。普通工作区使用通配订阅不会收到这些事件。

结束事件包含 data.call.id、reason 和 duration_seconds。时长是接通时间向下取整后的秒数，因此 0 本身不能证明未接通，需要同时记录接通事件。创建阶段同步失败可能没有结束回调，应单独处理 HTTP 错误。

签名校验和按事件 ID 去重遵循 Webhook 投递文档。业务系统可以据此安排跟进，但通话结束不会自动代表客户的问题已经解决。

当前内测范围与边界

本次内测支持 通过浏览器流程发起的 WhatsApp 单聊语音和视频通话。群通话、频道通话、其他消息平台的通话以及呼入处理，都不在当前范围内。文档中的 call.incoming 是预留契约，出现在事件目录中不代表已经开放来电接听。

录音、转写、SIP/PBX 集成及 AI 自动语音客服，也不是本次内测提供的能力。UnifyPort 使用非官方接口；本文介绍的是 UnifyPort 自身的通话契约，不应将其理解为 Meta 官方 WhatsApp Business Calling API。

工作区的 is_beta 是默认关闭的只读标识，需由技术支持开通资格。未获资格的工作区调用通话 API，会返回 403 beta_feature_not_enabled，数值错误码为 41002。设置 metadata 或发送工作区 PATCH 都不能自行开通。

申请前的常见问题

可以只填写手机号发起通话吗？

不可以。需要使用选中的 WhatsApp 消息账号下真实的 conversation_id，并设置 to.type: user。

创建 API 会立即拨号吗？

不会。API 先准备通话链接，由人工在 expires_at 到期前打开链接并点击 Start call 才拨号。

通话最长只有 2 分钟吗？

不是。2 分钟是从创建起计算的默认准备期，不是已经接通的通话时长上限。

开通内测后可以接听客户来电吗？

暂不可以。当前内测未开放呼入，is_beta: true 的工作区也不例外。

为团队申请通话内测

联系技术支持，申请工作区通话内测资格。为了便于说明需求，可以提供工作区 ID、计划使用的 WhatsApp 客服场景，以及需要语音还是视频。这些是有助于沟通的信息，不是自动开通流程；申请时不要发送 API Key 或私密通话链接。

资格开通后，按照创建通话文档，从一个明确选中的测试会话开始，接入客服的浏览器发起流程。围绕团队想改善的沟通步骤，评估人工通话如何融入现有客服应用。