← API 参考
账号POST

创建账号

创建渠道账号。auth_mode 必填且仅可为 qrcode、code 或 session。当 provider 与 auth_mode 组合要求手机号时（例如 WhatsApp + auth_mode=code），必须通过 provider_data.phone 提供；该值会持久化并在后续认证动作中复用。

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

请求头

X-Api-Key
string必填

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

Content-Type
string必填

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

路径参数

该接口没有路径参数。

请求体

name
string

可读的账号名称。

provider
string必填

客户可用的渠道标识：telegram、whatsapp、line、twitter、zalo 或 tiktok。

enum: telegram, whatsapp, line, twitter, zalo, tiktok, x, x_client, twitter_client

region
string必填

用于分配的渠道区域。请通过 列出渠道区域 选择 allocatable: true 的区域。

minLength: 1

status
string

账号业务状态，例如 active 或 inactive。

runtime_status
string

渠道支持通过账号配置修改时，请求设置的运行时状态。

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

auth_mode
string必填

创建账号时必填；认证流程仅可为 qrcode、code 或 session。

enum: qrcode, code, session

capabilities[]
string[]

账号能力列表。PATCH 时省略表示保留，传 [] 表示清空，null 非法。

metadata
object

平台侧元数据。PATCH 时省略表示保留，传 {} 表示清空，null 非法。

provider_account_ref
string

渠道侧账号标识，通常在授权完成后由系统写入。

provider_data
object

渠道专属配置。PATCH 时省略表示保留，传 {} 表示清空，null 非法；请勿记录密钥字段。

proxy
object

该账号可选的出站代理配置。

响应体

id
string

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

name
string

可读的账号名称。

provider
string

渠道标识，例如 telegram、whatsapp、line、twitter、zalo 或 tiktok。

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

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 不同。

响应

201
201 Created

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

400
请求错误

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

401
未授权

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

409
冲突

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

500
服务端错误

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

503
服务不可用

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

请求

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Telegram Production",
  "provider": "telegram",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": {},
  "metadata": {
    "env": "production"
  },
  "provider_account_ref": "provider-side-identifier"
}'

响应

{
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "global",
    "status": "active",
    "runtime_status": "stopped",
    "auth_mode": "qrcode",
    "capabilities": ["send_message", "receive_message"],
    "provider_account_ref": "provider-side-identifier"
  }
}