账号授权

导入会话

通过导入已有 session URL 或 cookie/会话载荷完成认证。客户端示例请使用占位符，切勿在日志中暴露真实会话内容。

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

调用前准备

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

WhatsApp Protocol 是独立渠道，使用 provider=whatsapp-protocol。目前仅支持会话导入（auth_mode=session），通过已有会话凭证完成授权。 WhatsApp Protocol 接入授权

参数从哪里取得

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

请求

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/auth/session" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "session_url": "https://example.com/account.session"
}'

请求参数

请求头

X-Api-Key

string必填

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

Content-Type

string必填

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

路径参数

account_id

string必填

用于该 authentication 路由的标识符。

请求体

session_url

string

已有渠道会话的 URL 或引用。

format: uri

whatsapp-protocol

object

WhatsApp Protocol 会话导入凭证，只能通过此嵌套对象提交至 /v1/accounts/{account_id}/auth/session，不能通过 provider_data 提交。提供该对象时，phone、static_pub_key、static_pri_key、identity_pub_key 和 identity_pri_key 必填。响应不回显协议密钥或其他敏感凭证。phone 用于身份一致性校验；协议公钥、私钥仅供上游启动使用。edge_routing 由平台固定注入，不得提交。

phone

string

手机号允许包含空格、连字符、括号或加号；服务端会归一化为正数字符串。

minLength: 1

platform

integer

WhatsApp Protocol 会话导入的平台值（int32）。

format: int32

app_version

string

WhatsApp Protocol 会话导入的应用版本。

server_address

string

WhatsApp Protocol 会话导入的渠道服务器地址。

fallback_server_addresses[]

string[]

WhatsApp Protocol 会话导入的备用服务器地址列表。

country

string

WhatsApp Protocol 会话导入的国家代码。

device

integer

WhatsApp Protocol 会话导入的设备值（uint32）。

format: uint32

static_pub_key

string

协议公钥；只写。

minLength: 1

static_pri_key

string

协议私钥；只写。

minLength: 1

identity_pub_key

string

身份公钥；只写。

minLength: 1

identity_pri_key

string

身份私钥；只写。

minLength: 1

hash

string

已弃用的兼容字段；当前值被忽略且不保存，建议省略。

peer_kem_public

string

对端 KEM 公钥；只写。

auth_hex_data

string

当前认证十六进制数据；只写。

authhexdata

string

已弃用的旧版认证十六进制数据字段；只写。

pq_handshake_mode

string

WhatsApp Protocol 会话导入的 PQ 握手模式。

use_xxkem_handshake

boolean

WhatsApp Protocol 会话导入是否使用 XXKEM 握手。

如何理解结果

先读取授权结果，再检查 runtime_status。完成会话导入与建立在线连接是不同阶段。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "authorized"
  }
}

响应体

account_id

string

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

status

string

当前授权流程状态，例如 pending_auth、awaiting_qr_scan、awaiting_code、pending、passkey_required、passkey_pending、passkey_confirmation、passkey_confirmation_sent、authorized 或 failed。

响应

200

200 OK

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

400

请求错误

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

401

未授权

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

409

冲突

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

500

服务端错误

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

502

上游网关错误

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

失败后怎么处理

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

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