账号

列出账号

列出当前工作区的渠道账号。账号的认证状态通过 Authentication 接口暴露。

GEThttps://api.unifyport.ai/v1/accounts

调用前准备

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

请求参数

请求头

X-Api-Key

string必填

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

查询参数

limit

integer

每页最多返回的账号数，范围为 1 至 100，省略时为 20。非法值或重复传入 limit 时返回 400 invalid_request（numeric_code=10000）；续页可调整此值。

minimum: 1 · maximum: 100

cursor

string

账号列表的不透明游标。省略或传入空字符串时读取第一页；续页原样回传上次响应的 data.next_cursor。仅适用于签发时的 workspace；非法、重复传入或跨 workspace 使用 cursor 时返回 400 invalid_request（numeric_code=10000）。

请求体

该接口无需 JSON 请求体。

如何理解结果

按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "acc_example",
        "name": "Telegram Production",
        "provider": "telegram",
        "region": "global",
        "status": "active",
        "runtime_status": "running",
        "auth_mode": "qrcode",
        "capabilities": [
          "send_message",
          "receive_message"
        ],
        "metadata": {
          "env": "production"
        },
        "provider_account_ref": "provider-side-identifier",
        "provider_profile": {
          "id": "778899",
          "phone": "8600000000000",
          "username": "production_bot",
          "display_name": "Production Bot",
          "first_name": "Production",
          "last_name": "Bot",
          "avatar_url": "https://example.com/avatar.jpg",
          "bio": "Customer support"
        }
      }
    ],
    "has_more": false
  }
}

响应体

id

string

账号唯一标识（acc_...），用于账号维度的路由。

name

string

可读的账号名称。

provider

string

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

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

region

string

该账号被分配到的渠道区域。

status

string

账号生命周期状态，例如 active。

runtime_status

string

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

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

auth_mode

string

账号使用的认证流程：code、qrcode 或 session。

capabilities[]

string[]

账号已启用的能力，例如 send_message 与 receive_message。

metadata

object

存储在账号上的自有环境标签。

provider_account_ref

string

渠道侧标识，可附加用于将该账号与你自有系统关联。

proxy

object

账号绑定的出站代理配置，未配置时省略。

provider_profile

object

渠道上报的资料，例如 display_name；账号认证完成前不返回。

id

string

渠道侧账号标识。WhatsApp 返回 LID；账号资料同步完成前可能省略。

phone

string

已归一化的账号手机号，不含空格、连字符和开头加号。

username

string

渠道上报的用户名（如有）。

display_name

string

账号展示名称；WhatsApp 按 BusinessName 优先、PushName 回退的规则生成。

push_name

string

WhatsApp 当前账号设置的 PushName；其他渠道不定义该字段语义。

business_name

string

WhatsApp BusinessName；渠道未返回时该字段缺失。

first_name

string

渠道上报的名字（如有）。

last_name

string

渠道上报的姓氏（如有）。

avatar_url

string

渠道上报的账号头像 URL（如有）。

bio

string

渠道上报的账号简介或状态文本（如有）。

platform

string

WhatsApp 配对时上报的登录平台标识。请将其视为不透明字符串并兼容未知值；其他渠道不定义该字段语义。该字段与 device_platform 不同。

has_more

boolean

账号列表是否还有下一页。

next_cursor

string

账号列表下一页的不透明游标，仅在 has_more=true 时返回；续页时原样传入 cursor，末页省略此字段。

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

500

服务端错误

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

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。错误码参考

invalid_request · 10000 · 400: 检查必填字段、格式和渠道条件，修正请求后再调用。
invalid_api_key · 11001 · 401: 检查 X-Api-Key 是否正确、工作区是否有效。