← API 参考
快速开始

账号生命周期

一个账号携带三个相互独立的状态：status（由你设置的业务开关）、GET /v1/accounts/{id}/auth 返回的认证状态，以及 runtime_status（实时连接状态）。webhook 载荷以 auth_status 和 runtime_status 暴露后两者——注意 REST 账号对象本身没有名为 auth_status 的字段。

认证状态机

  • pending_auth

    账号创建后的初始状态；尚未发起任何流程。

  • awaiting_qr_scan

    二维码流程进行中；auth_payload 携带待渲染的二维码内容。

  • awaiting_code

    验证码流程进行中；WhatsApp 场景下需在手机上输入 auth_payload 中的 verify_code。

  • awaiting_password

    验证码之后，渠道要求输入两步验证密码。

  • authorized

    认证完成，运行时已自动启动。

  • failed

    流程失败；last_error 携带原因。发起新流程即可重试。

状态迁移
1
pending_auth→awaiting_qr_scan

POST /auth/qr/start 发起二维码流程。

2
pending_auth→awaiting_code

POST /auth/start 发起验证码流程。

3
awaiting_code→awaiting_password

渠道要求输入两步验证密码。

4
awaiting_qr_scan→authorized

渠道确认扫码成功。

5
awaiting_code→authorized

验证码（或 WhatsApp 配对）被接受。

6
awaiting_password→authorized

密码被接受。

7
authorized→pending_auth

渠道使会话失效——触发 account.auth.required 事件，需要发起新流程。

8
awaiting_*→failed

任一等待步骤中渠道上报失败（account.auth.failed 事件）。

9
awaiting_*→pending_auth

POST /auth/cancel 放弃当前进行中的流程。

运行时状态机

  • unknown

    账号创建后的初始状态；平台没有渠道最新上报时也会回到该状态——调用 /runtime/refresh 重新同步。

  • starting

    启动进行中；渠道正在将会话拉上线。

  • running

    已连接，可正常收发消息。

  • reconnecting

    连接断开，自动或手动重连进行中。

  • disconnected

    渠道上报会话已离线；通过 reconnect 或 start 恢复。

  • stopping

    停止进行中。

  • stopped

    未连接，停止完成后的状态。

  • error

    运行时遇到不可恢复错误；last_error 携带原因。

状态迁移
1
unknown→starting

授权成功后自动启动。

2
stopped→starting

显式调用 POST /runtime/start。

3
starting→running

渠道会话上线（account.started 事件）。

4
running→reconnecting

连接断开，或调用了 POST /runtime/reconnect。

5
reconnecting→running

连接重新建立。

6
running→disconnected

渠道上报会话离线（account.status.updated 事件）。

7
disconnected→running

POST /runtime/reconnect 或 /runtime/start 将其拉回在线。

8
running→stopping

POST /runtime/stop 发起优雅停止。

9
stopping→stopped

停止完成。

10
*→error

任意时刻发生不可恢复的渠道错误。

11
*→unknown

缺少渠道最新上报；POST /runtime/refresh 重新同步该值。

备注

  • 账号的 status 归你管（业务开关，创建时设置或通过 PATCH 修改）。另外两个状态归平台所有、只读：认证状态通过 GET /v1/accounts/{id}/auth 的 status 字段读取，runtime_status 直接挂在账号对象上。
  • 授权成功会自动启动运行时——之后再调用 POST /runtime/start 是无害的空操作。
  • 处于 authorized 状态时，POST /auth/start、/auth/qr/start 和 /auth/session 会被拒绝并返回 409 account_already_authorized。确实需要重新走流程时，请先调用 POST /auth/cancel。
  • account.auth.required 事件表示渠道使会话失效：认证状态脱离 authorized，auth_payload 携带重新认证所需的材料（例如新的二维码）。
  • 每次运行时变化都会推送 account.status.updated 事件，同时携带 auth_status 和 runtime_status——请通过 webhook 维护本地副本，而不是轮询。