API 参考

通话

挂断通话

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

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

支持的渠道

WhatsApp

调用前准备

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

创建通话前完成 WhatsApp 授权,并检查 runtime_status=running。目标使用当前账号下私聊会话的 conversation_id。

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

请求参数

请求头

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;创建冲突时先查询当前通话。重试创建或挂断前确认当前通话状态。 错误码参考

结合当前操作读取 HTTP 状态、error.code 和 error.numeric_code。数字码按字符串处理。保留 request_id 排障;它不是幂等键或任务标识。

invalid_request · 10000 · 400

检查 JSON 请求体和必填字段。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON;message 随实际原因变化 · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
invalid_target_workspace · 11003 · 400

工作区覆盖目标为空或格式无效。移除覆盖请求头,改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON;message 随实际原因变化 · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
provider_invalid_request · 30001 · 400

检查渠道专属字段及其格式。

处理与重试: 按当前操作与渠道条件修正参数后再请求。重复提交相同的无效请求不会解决错误。

示意 JSON;message 随实际原因变化 · 400 · 30001
{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}
invalid_api_key · 11001 · 401

检查 API Key 是否正确且已启用。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示意 JSON;message 随实际原因变化 · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

请添加 X-Api-Key 请求头。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示例 · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

请求尝试使用此 API Key 无权使用的工作区覆盖。移除覆盖请求头,改用目标工作区所属的 API Key。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示例 · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
account_not_found · 20020 · 404

核对 account_id,并使用账号所属工作区的 X-Api-Key。此工作区下未找到的账号不能用当前 Key 访问。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON;message 随实际原因变化 · 404 · 20020
{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
call_not_found · 38003 · 404

当前账号和工作区下不存在该通话。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示例 · 404 · 38003
{
  "request_id": "req_example",
  "error": {
    "code": "call_not_found",
    "numeric_code": "38003",
    "message": "Call not found"
  }
}
target_workspace_not_found · 11004 · 404

覆盖指定的工作区不存在或不可用。核对工作区归属,移除覆盖请求头并使用目标工作区 API Key;重复请求不会增加访问权限。

触发条件: 适用于携带 X-Workspace-Id 工作区覆盖请求头的请求。

处理与重试: 核对目标标识、资源归属与当前工作区。不要把已确认缺失或无法访问的目标当作临时服务故障自动重试。

示意 JSON;message 随实际原因变化 · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
account_binding_not_found · 30006 · 409

账号尚无有效的渠道连接绑定,请检查账号状态。

处理与重试: 查询授权与运行态,再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出;依赖连接的业务操作前确认 running。

示意 JSON;message 随实际原因变化 · 409 · 30006
{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}
call_already_active · 38000 · 409

账号已有受管理的活跃通话。核对已知通话与本次动作意图;此错误本身不要求挂断,也不要求反复调用同一个失败查询。

处理与重试: 保留 request_id 与结构化错误码,先排查当前操作,再决定下一步。

示意 JSON;message 随实际原因变化 · 409 · 38000
{
  "request_id": "req_example",
  "error": {
    "code": "call_already_active",
    "numeric_code": "38000",
    "message": "Account already has an active call"
  }
}
egress_configuration_pending · 20032 · 409

当前无法确认或读取平台默认网络配置;这不表示账号已退出登录。

触发条件: 本操作使用平台分配的网络容量或账号固定的默认网络配置。

处理与重试: 保留 request_id,再次写入前核对账号或创建结果。等待容量或配置恢复,或联系支持;不要自动反复创建账号、更换网络或重启账号。

示意 JSON;message 随实际原因变化 · 409 · 20032
{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}
provider_not_ready · 30009 · 409

连接尚未就绪,请检查授权及 runtime_status 后再决定是否重试。

处理与重试: 查询授权与运行态,再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出;依赖连接的业务操作前确认 running。

示意 JSON;message 随实际原因变化 · 409 · 30009
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}
provider_not_ready · 30014 · 409

此账号所需的渠道实例缺失。这是运行实例可用性问题,不证明授权已过期。

处理与重试: 查询授权与运行态,再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出;依赖连接的业务操作前确认 running。

适用渠道: WhatsApp

示意 JSON;message 随实际原因变化 · 409 · 30014
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}
provider_not_ready · 30015 · 409

渠道运行进程已停止。启动前确认这是否为预期状态;运行态停止本身不等于已登出。

处理与重试: 查询授权与运行态,再按目标状态和渠道支持选择刷新、启动或重连。连接问题本身不证明已登出;依赖连接的业务操作前确认 running。

适用渠道: WhatsApp

示意 JSON;message 随实际原因变化 · 409 · 30015
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}
call_control_failed · 30010 · 500

渠道未能完成本次操作。message 可能在 “Provider operation failed:” 后附带原始原因;原因文本可变,不是稳定的程序接口。

触发条件: 适用于渠道未提供更具体失败分类的情况,保留当前操作的错误。

处理与重试: 创建或结束通话前,查询当前受管理通话及 call_id/state。preparing 不表示拨号或接通;ended 与 failed 都是终态,不要仅因 failed 重复挂断。

适用渠道: WhatsApp

示意 JSON;message 随实际原因变化 · 500 · 30010
{
  "request_id": "req_example",
  "error": {
    "code": "call_control_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}
call_control_failed · 38004 · 500

未能查询或结束通话;按本次动作核对通话状态。

处理与重试: 创建或结束通话前,查询当前受管理通话及 call_id/state。preparing 不表示拨号或接通;ended 与 failed 都是终态,不要仅因 failed 重复挂断。

示意 JSON;message 随实际原因变化 · 500 · 38004
{
  "request_id": "req_example",
  "error": {
    "code": "call_control_failed",
    "numeric_code": "38004",
    "message": "Failed to control call"
  }
}
unsupported_by_provider · 30003 · 501

渠道不支持此操作,请选择能力表中支持的操作。

处理与重试: 选择文档列为支持的渠道与动作。重复请求不会增加能力或开通内测权限。

示例 · 501 · 30003
{
  "request_id": "req_xxx",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}
provider_adapter_not_found · 30004 · 502

渠道服务暂不可用,请检查状态或稍后再试;重试写操作前先确认上次结果。

处理与重试: 创建或结束通话前,查询当前受管理通话及 call_id/state。preparing 不表示拨号或接通;ended 与 failed 都是终态,不要仅因 failed 重复挂断。

示意 JSON;message 随实际原因变化 · 502 · 30004
{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}
provider_unavailable · 30002 · 502

渠道服务暂不可用,请检查状态或稍后再试;重试写操作前先确认上次结果。

处理与重试: 创建或结束通话前,查询当前受管理通话及 call_id/state。preparing 不表示拨号或接通;ended 与 failed 都是终态,不要仅因 failed 重复挂断。

示例 · 502 · 30002
{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}
provider_unavailable · 30010 · 502

渠道未能完成本次操作。message 可能在 “Provider operation failed:” 后附带原始原因;原因文本可变,不是稳定的程序接口。

处理与重试: 创建或结束通话前,查询当前受管理通话及 call_id/state。preparing 不表示拨号或接通;ended 与 failed 都是终态,不要仅因 failed 重复挂断。

适用渠道: WhatsApp

示例 · 502 · 30010
{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}
call_service_unavailable · 38001 · 503

通话服务不可用,请检查 Provider/Gateway 连接和配置。

处理与重试: 创建或结束通话前,查询当前受管理通话及 call_id/state。preparing 不表示拨号或接通;ended 与 failed 都是终态,不要仅因 failed 重复挂断。

示意 JSON;message 随实际原因变化 · 503 · 38001
{
  "request_id": "req_example",
  "error": {
    "code": "call_service_unavailable",
    "numeric_code": "38001",
    "message": "Call service unavailable"
  }
}