API 参考

账号连接

刷新运行时状态

同步账号最新的渠道运行时状态。runtime_status 的取值统一为 unknown、starting、running、stopping、stopped、reconnecting、disconnected、error 之一；provider 私有的取值会先被规范化到这一集再返回。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/runtime/refresh

支持的渠道

all

调用前准备

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

先查询当前授权和运行态，再按目标选择操作。启动、停止、刷新和重连的用途不同；账号离线本身不代表需要重新授权。

参数从哪里取得
account_id
从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号

请求参数

请求头

X-Api-Key
string必填

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

Content-Type
string必填

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

路径参数

account_id
string必填

用于该 runtime 路由的标识符。

请求体

该接口接收空 JSON 对象；请按请求示例发送 {}。

如何理解结果

读取刷新后的 runtime_status，了解当前连接状态。刷新成功不表示账号在线；根据返回状态和授权提示选择下一步。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "runtime_status": "running"
  }
}

响应体

account_id
string

该响应所对应的渠道账号。

provider
string

渠道标识。调用其他接口时原样使用 API 返回的值；此接口的返回范围见下方枚举。

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

action
string

本次请求的动作。

enum: refresh_status, start, stop, reconnect

operation_status
string

运行时动作被接受或完成的状态。

runtime_status
string

标准化的运行时状态，取值之一：unknown、starting、running、stopping、stopped、reconnecting、disconnected 或 error。

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

runtime_error
string

动作未完成时的渠道运行时错误。

auth_required
boolean

为 true 时，继续对应渠道的授权流程。仅在渠道返回授权材料，或已有经确认的授权流程尚未完成时返回此提示。未返回或为 false 不代表在线，连接状态请查看 runtime_status；仅有 disconnected 不能推断需要重新授权。运行态接口不返回 code、qrcode、auth_payload 或 provider_data，请从对应渠道的授权接口获取授权材料。

auth_status
string

可选的授权状态，例如 pending、awaiting_qr_scan 或 passkey_required。有授权材料或经确认的未完成授权流程时才会返回。按渠道指南继续操作；完整状态与授权材料从授权接口查询，连接状态查看 runtime_status。

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

409

冲突

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

500

服务端错误

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

502

上游网关错误

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

失败后怎么处理

检查 HTTP 状态、error.code/numeric_code 和当前状态，保留 request_id。核对所选动作及渠道支持范围；有明确授权提示时才继续授权，重试前先确认运行态。 错误码参考

invalid_request · 10000 · 400
检查必填字段、格式和渠道条件，修正请求后再调用。
missing_api_key · 11000 · 401
检查 X-Api-Key 是否正确、工作区是否有效。
invalid_api_key · 11001 · 401
检查 X-Api-Key 是否正确、工作区是否有效。
provider_not_ready · 30009 · 409
检查 HTTP 状态、error.code/numeric_code 和当前状态，保留 request_id。核对所选动作及渠道支持范围；有明确授权提示时才继续授权，重试前先确认运行态。