← API 參考
快速上手

帳號生命週期

一個帳號帶住三個互相獨立嘅狀態：status（由你設定嘅業務開關）、GET /v1/accounts/{id}/auth 回傳嘅認證狀態，同埋 runtime_status（實際連線狀態）。Webhook 載荷會以 auth_status 同 runtime_status 暴露後兩個——留意 REST 帳號物件本身係冇 auth_status 呢個欄位嘅。

認證狀態機

  • pending_auth

    帳號啱啱建立之後嘅初始狀態；仲未開始任何流程。

  • awaiting_qr_scan

    QR 流程進行緊；auth_payload 帶住要 render 嘅 QR 內容。

  • awaiting_code

    驗證碼流程進行緊；WhatsApp 嘅話，auth_payload 入面嘅 verify_code 就係要打入手機嗰個。

  • awaiting_password

    渠道喺驗證碼一步之後仲要求二階段密碼。

  • authorized

    認證完成，執行環境會自動啟動。

  • failed

    流程失敗咗；原因喺 last_error。想重試就開個新流程。

轉換
1
pending_auth→awaiting_qr_scan

POST /auth/qr/start 開始一個 QR 流程。

2
pending_auth→awaiting_code

POST /auth/start 開始一個驗證碼流程。

3
awaiting_code→awaiting_password

渠道要求二階段密碼。

4
awaiting_qr_scan→authorized

渠道確認咗 QR 掃描。

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

    渠道回報個會話已離線；重連或者重新啟動就可以恢復。

  • 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 會重新同步個值。

備註

  • Account.status 係屬於你嘅（建立嗰陣或者經 PATCH 設定嘅業務開關）。其餘兩個由平台話事、只讀：認證狀態經 GET /v1/accounts/{id}/auth 攞（睇佢嘅 status 欄位），runtime_status 就喺帳號物件上面。
  • 授權成功會自動啟動執行環境——之後再叫 POST /runtime/start 係無害嘅 no-op。
  • 處於 authorized 期間，POST /auth/start、/auth/qr/start 同 /auth/session 會被拒，回 409 account_already_authorized。如果真係要重新行一次流程，請先叫 POST /auth/cancel。
  • account.auth.required 事件代表渠道令個會話失效咗：認證狀態會跌出 authorized，auth_payload 帶住重新認證需要嘅材料（例如一個新 QR）。
  • 執行環境每次變化都會以 account.status.updated 事件推送，一齊帶住 auth_status 同 runtime_status——請靠 webhook 同步你本地嗰份，唔好靠輪詢。