API 参考

账号授权

开始验证码认证

使用账号已保存的手机号启动授权。WhatsApp 从 data.verify_code 读取配对码，在手机端输入，无需提交到 /auth/code。Telegram 将用户收到的验证码提交到 /auth/code，需要二次密码时再调用 /auth/password。awaiting_code 不代表授权成功。

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/auth/start

支持的渠道

TelegramWhatsApp

调用前准备

在服务端使用资源所属工作区的 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必填

用于该 authentication 路由的标识符。

请求体

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

如何理解结果

按本次授权动作读取 status/auth_status 和实际返回的 auth_payload。需要用户操作时按渠道指南继续；authorized 表示授权完成，发送前仍需检查 runtime_status。

响应 200 · WhatsApp

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "whatsapp",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "verify_code": "ABCD-EFGH"
  }
}

响应 200 · Telegram

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "provider": "telegram",
    "action": "start_auth",
    "status": "awaiting_code",
    "auth_status": "awaiting_code",
    "auth_payload": {
      "type": "code"
    }
  }
}

响应体

provider
string

本次授权动作对应的渠道。

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

action
string

请求的授权动作，值为 start_auth。

enum: start_auth

status
string

当前授权状态；awaiting_code 表示等待用户操作，authorized 才表示授权完成。

auth_status
string

当前授权步骤的标准状态，通常与 status 一致。

verify_code
string

WhatsApp 手机号配对码，直接位于 data 下。交由用户在手机端输入，无需提交到 /auth/code；响应不保证提供过期时间。

auth_payload
object

渠道特定的授权提示。Telegram 可返回 type=code，不包含用户收到的验证码。

type
string

授权提示类型；Telegram 验证码步骤为 code。

响应

200

200 · WhatsApp

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

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 是否正确、工作区是否有效。
account_already_authorized · 20016 · 409
账号已经授权，请复用；确需重新授权时先取消当前授权。