账号

更新账号

部分更新账号元数据与渠道配置。未传字段（包括 provider 与 region）保留现值；null 非法；空数组或空对象用于清空集合或对象字段。重复渠道身份返回 409 duplicate_provider_account。

PATCHhttps://api.unifyport.ai/v1/accounts/{account_id}

支持的渠道

all

调用前准备

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

参数从哪里取得

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

请求

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

请求参数

请求头

X-Api-Key

string必填

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

Content-Type

string必填

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

路径参数

account_id

string必填

用于该 accounts 路由的标识符。

请求体

name

string

可读的账号名称。

provider

string

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

enum: telegram, whatsapp, line, twitter, facebook, zalo, tiktok, whatsapp-protocol, 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 非法。TikTok provider_data.enable_comment 仅接受 Boolean，默认 false；字符串、数字、null 返回 400 invalid_request。在线修改需 reconnect，start 成功不证明配置已应用；关闭不撤回已排队事件。Telegram 的 code、qrcode、session 均可省略 api_id 和 api_hash；自定义凭证须为同一应用的成对字符串。创建时未指定自定义凭证、非空配置替换时缺省凭证字段，均使用平台默认值；所需默认配置不可用时请求失败。平台默认凭证变更不会替换已有账号凭证。请勿记录密钥。

proxy

object

该账号可选的出站代理配置。PATCH 时自定义代理优先；清空后恢复账号创建时的默认配置。旧账号沿用原清空行为。

如何理解结果

按本接口的响应字段和 HTTP 状态判断结果，再通过相关操作选择下一步。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "status": "active",
    "auth_mode": "code"
  }
}

响应体

provider_profile

object

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

id

string

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

device_id

integer

仅 WhatsApp 账号详情在可确认当前会话时提供的可选登录设备编号；重新授权后可能变化，不作为永久设备标识。

minimum: 0 · maximum: 65535

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

billing

object

消息账号已付周期，仅余额账号存在；不能从钱包余额推断已购买。

period_start_at

string

服务端返回的已付周期起点。

format: date-time

period_end_at

string

服务端返回的已付周期终点。

format: date-time

amount_minor

integer

服务端不可变金额，单位为 USD 分，须按精确整数处理。

minimum: 1 · format: int64

currency

string

仅 USD。

operation_id

string

来自 billing.operation_id 或删除响应的公开标识，在原工作区原样复用。

state

string

计费或操作状态，不证明账号已授权、在线或退款已入账。

enum: ACTIVE, DELETING, DELETED, COMPENSATED, REVIEW

id

string

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

name

string

可读的账号名称。

provider

string

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

enum: telegram, whatsapp, line, twitter, facebook, 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。TikTok 支持 qrcode 和 session，但不支持两种模式原地切换。

capabilities[]

string[]

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

metadata

object

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

provider_account_ref

string

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

proxy

object

客户显式配置的代理；不返回平台默认出口凭据。

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

403

禁止访问

请求已识别，但不允许执行该操作。

404

未找到

未找到请求的资源；请结合 error.code 和当前操作核对。

409

冲突

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

422

无法处理的实体

请求格式有效，但无法解析目标渠道会话。

500

服务端错误

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

502

上游网关错误

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

失败后怎么处理

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

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

auth_mode_phone_required · 20019 · 400

此授权方式要求创建账号时填写 provider_data.phone。

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

示意 JSON；message 随实际原因变化 · 400 · 20019

{
  "request_id": "req_example",
  "error": {
    "code": "auth_mode_phone_required",
    "numeric_code": "20019",
    "message": "Phone number is required for this auth mode"
  }
}

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"
  }
}

unsupported_provider_auth_mode · 20018 · 400

请使用此渠道支持的 auth_mode。

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

示意 JSON；message 随实际原因变化 · 400 · 20018

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_provider_auth_mode",
    "numeric_code": "20018",
    "message": "Auth mode not supported by this provider"
  }
}

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 与结构化错误码，先排查当前操作，再决定下一步。

示意 JSON；message 随实际原因变化 · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

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"
  }
}

duplicate_provider_account · 20015 · 409

工作区内已有另一个账号绑定相同的渠道身份。

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

示意 JSON；message 随实际原因变化 · 409 · 20015

{
  "request_id": "req_example",
  "error": {
    "code": "duplicate_provider_account",
    "numeric_code": "20015",
    "message": "A provider account with the same identity already exists in this workspace"
  }
}

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 · 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"
  }
}

egress_change_not_supported · 20034 · 422

账号使用固定默认网络，不支持通过普通账号更新修改其地区或渠道。

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

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

示意 JSON；message 随实际原因变化 · 422 · 20034

{
  "request_id": "req_example",
  "error": {
    "code": "egress_change_not_supported",
    "numeric_code": "20034",
    "message": "The requested network change is not supported"
  }
}

update_account_failed · 20003 · 500

更新账号：未分类错误中断本次改动，需确认资源最终状态。

处理与重试: 先读取资源当前状态，确认上一次改动结果，再决定是否重试。保留 request_id；结果未知时不要自动重复写入。

示意 JSON；message 随实际原因变化 · 500 · 20003

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "20003",
    "message": "Failed to update account"
  }
}

update_account_failed · 20020 · 500

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

触发条件: 适用于账号不存在的情况；保留原 HTTP 状态和操作 code，通过 numeric_code 细分账号缺失。

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

示意 JSON；message 随实际原因变化 · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

update_account_failed · 30010 · 500

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

触发条件: 仅适用于真正切换授权模式并调用 WhatsApp 退出的情况；普通账号资料更新不会触发此数字细分。

处理与重试: 先读取资源当前状态，确认上一次改动结果，再决定是否重试。保留 request_id；结果未知时不要自动重复写入。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 500 · 30010

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}

update_account_failed · 30021 · 500

本次请求时账号未连接到消息平台。WhatsApp 添加联系人可返回 500 / create_contact_failed / 30021。这不证明账号已退出登录，也不保证当前运行态仍为 disconnected；先查询当前状态，再选择恢复动作。

触发条件: 仅适用于真正切换授权模式并调用 WhatsApp 退出的情况；普通账号资料更新不会触发此数字细分。

处理与重试: 暂停依赖连接的业务操作。先调用 POST /v1/accounts/{account_id}/runtime/refresh，按最新状态恢复，确认 runtime_status=running 后再请求业务接口。重发前确认上一次写入结果。

适用渠道: WhatsApp

示意 JSON；message 随实际原因变化 · 500 · 30021

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "30021",
    "message": "Account is not connected to the messaging platform"
  }
}

provider_unavailable · 30002 · 502

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

处理与重试: 先读取资源当前状态，确认上一次改动结果，再决定是否重试。保留 request_id；结果未知时不要自动重复写入。

示例 · 502 · 30002

{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}