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 在手機端輸入 data.verify_code；Telegram 將收到的驗證碼提交至 /auth/code。

  • awaiting_password

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

  • authorized

    帳戶已完成授權。自動開始連線不代表已就緒，傳送前仍需檢查 runtime_status。

  • 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 放棄進行緊嘅流程。

WhatsApp Passkey 子流程

  • passkey_required

    WhatsApp 要求瀏覽器提供 WebAuthn 憑證之後先可以繼續 QR 授權。

  • passkey_pending

    WebAuthn 憑證已提交，等緊渠道處理。

  • passkey_confirmation

    渠道要求用戶明確確認 Passkey 操作。

  • passkey_confirmation_sent

    確認已送出，渠道正完成授權。

  • authorized

    帳戶已完成授權。自動開始連線不代表已就緒，傳送前仍需檢查 runtime_status。

  • failed

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

轉換
1
passkey_required→passkey_pending

經託管頁面或者 POST /auth/passkey-response 提交序列化嘅 WebAuthn 憑證。

2
passkey_pending→passkey_confirmation

渠道要求用戶確認 Passkey 操作。

3
passkey_confirmation→passkey_confirmation_sent

POST /auth/passkey-confirm 送出用戶確認。

4
passkey_pending→authorized

渠道唔使額外確認，直接接受憑證。

5
passkey_confirmation_sent→authorized

渠道接受已確認嘅憑證。

6
passkey_*→failed

渠道拒絕或者無法完成 Passkey 流程。

執行環境狀態機

  • 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 會明確要求啟動；請先檢查實際 runtime_status，只喺仍需啟動時呼叫，並處理返回嘅 operation_status。
  • 處於 authorized 期間，POST /auth/start、/auth/qr/start 同 /auth/session 會被拒，回 409 account_already_authorized。如果真係要重新行一次流程，請先叫 POST /auth/cancel。
  • account.auth.required 表示目前授權需要用戶操作，可以喺首次授權或重新授權期間出現；唔可以單憑呢個事件推斷之前已授權或會話已失效。透過 data.auth_status 判斷等待步驟，從 data.auth_payload 取得可用嘅授權材料。
  • account.status.updated 用嚟回報渠道實際觀察到嘅認證或執行環境變化，但唔保證每個請求觸發嘅狀態轉移都會推送。執行動作或重連之後，請用 GET /v1/accounts/{account_id} 或 POST /runtime/refresh 同 webhook 狀態核對。