通话

创建通话beta

当前功能处于内测阶段，可联系技术支持申请开通工作区资格。

当前仅支持 WhatsApp 单聊语音和视频通话。准备一个保密的一次性 join_url。打开链接并点击 Start call 后才向对方拨号。

POSThttps://api.unifyport.ai/v1/calls

支持的渠道

调用前准备

在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。

确认工作区已开通内测资格。创建通话前完成 WhatsApp 授权，并检查 runtime_status=running。目标使用当前账号下私聊会话的 conversation_id。

在浏览器发起通话时需要允许麦克风，摄像头权限可选。

参数从哪里取得

account_id: 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。获取账号
to.id · to.type: 将 API 返回的当前账号下目标私聊 conversation_id 原样填入 to.id，to.type 使用 user；不要替换成手机号字符串。获取会话详情

请求

curl -X POST 'https://api.unifyport.ai/v1/calls' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "<conversation_id>",
    "type": "user"
  },
  "media_type": "video"
}'

请求参数

请求头

X-Api-Key

string必填

工作区 API Key，工作区由该请求头解析得到。

Content-Type

string必填

发送 JSON 请求体时使用 application/json。

请求体

account_id

string必填

当前工作区内的账号 ID。

pattern: ^acc_[A-Za-z0-9][A-Za-z0-9_-]*$

to

object必填

单聊通话目标。

id

string必填

填写当前账号下目标会话的 conversation_id，使用接口返回的原始值。

minLength: 1

type

string必填

目前仅支持 user；group/channel 返回不支持错误。

enum: user, group, channel

media_type

string必填

voice 为语音，video 为支持视频的通话。

enum: voice, video

如何理解结果

201 且 state=preparing 表示已准备通话，尚未向对方拨号。保存 call_id，在返回的 expires_at 前打开保密的 join_url 并点击 Start call；通过通话状态或 call.answered 确认接通。

备注

准备 WhatsApp 单聊语音或视频通话（media_type 为 voice/video）。to.id 使用 conversation_id，to.type 为 user；不接受手机号字符串，暂不支持群通话。准备期从创建起默认 2 分钟，实际截止时间以返回的 expires_at 为准；到期前打开 join_url 并点击 Start call 才拨号，不限制已接通通话时长。必须允许麦克风，摄像头可选；一次性链接请勿公开。

响应 201 · 201

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "direction": "outbound",
    "media_type": "video",
    "state": "preparing",
    "join_url": "https://calls.example.com/call/call_example#ticket=example-only",
    "expires_at": "2026-09-07T12:02:00Z"
  }
}

响应体

call_id

string

通话标识，挂断时也使用此值。

direction

string

通话方向。

enum: outbound

media_type

string

voice 为语音，video 为支持视频的通话。

enum: voice, video

state

string

当前通话状态。

enum: preparing

join_url

string

短期一次性 HTTPS 链接，请勿记录或公开。

format: uri

expires_at

string

准备阶段失效时间，RFC3339 格式。

format: date-time

响应

201

201 · 201

请求成功，响应体示例如上。

400

请求错误

请求体、路径或参数不合法。

401

未授权

X-Api-Key 请求头缺失或无效。

403

禁止访问

请求已识别，但不允许执行该操作。

404

未找到

未找到请求的资源；请结合 error.code 和当前操作核对。

409

冲突

当前操作与已有的渠道账号或资源冲突。

500

服务端错误

服务端遇到了未预期的错误。

501

渠道未实现

所选渠道尚未实现该操作。

502

上游网关错误

渠道适配器或上游渠道未能完成该操作。

503

服务不可用

所需的后端服务暂时不可用。

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code，保留 request_id。核对内测资格、账号和 call_id；创建冲突时先查询当前通话。重试创建或挂断前确认当前通话状态。错误码参考

invalid_request · 10000 · 400: 检查必填字段、格式和渠道条件，修正请求后再调用。
missing_api_key · 11000 · 401: 检查 X-Api-Key 是否正确、工作区是否有效。
invalid_api_key · 11001 · 401: 检查 X-Api-Key 是否正确、工作区是否有效。
account_not_found · 20020 · 404: 核对 account_id，并使用账号所属工作区的 X-Api-Key。此工作区下未找到的账号不能用当前 Key 访问。
unsupported_by_provider · 30003 · 501: 查看渠道能力指南，选择支持该动作的渠道或操作；重复请求不会增加支持范围。
beta_feature_not_enabled · 41002 · 403: 联系技术支持申请工作区内测资格。重复请求或在请求中修改 is_beta 都不会开通权限。
call_already_active · 38000 · 409: 先查询当前通话取得 call_id，等待结束或挂断后再创建新的通话。