通话

挂断通话beta

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

当前仅支持 WhatsApp 单聊语音和视频通话。使用 account_id 和 call_id 结束通话；忘记 call_id 时可先查询当前通话。

POSThttps://api.unifyport.ai/v1/calls/{call_id}/hangup

支持的渠道

调用前准备

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

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

参数从哪里取得

account_id: 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。获取账号
call_id: 使用当前账号创建通话或查询当前通话返回的 call_id。丢失该值时，先查询当前通话再挂断。查询当前通话

请求

curl -X POST 'https://api.unifyport.ai/v1/calls/call_example/hangup' \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example"
}'

请求参数

请求头

X-Api-Key

string必填

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

Content-Type

string必填

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

路径参数

call_id

string必填

用于该 calls 路由的标识符。

maxLength: 128 · pattern: ^[A-Za-z0-9][A-Za-z0-9_-]*$

请求体

account_id

string必填

当前工作区内的账号 ID。

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

如何理解结果

读取返回的 call_id 和 state。ended 和 failed 均为通话终态，重复挂断可能返回已有终态；不能将 HTTP 200 固定理解为 state=ended，也不要因 state=failed 自动重试。

响应 200 · 200

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "state": "ended",
    "direction": "outbound",
    "media_type": "voice"
  }
}

响应体

call_id

string

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

maxLength: 128

state

string

当前通话状态。

enum: ended, failed

direction

string

通话方向。

enum: inbound, outbound

media_type

string

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

enum: voice, video

响应

200

200 · 200

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

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_not_found · 38003 · 404: 检查 HTTP 状态和 error.code/numeric_code，保留 request_id。核对内测资格、账号和 call_id；创建冲突时先查询当前通话。重试创建或挂断前确认当前通话状态。