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 帶有要顯示的 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

渠道確認掃碼完成。

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 重新同步狀態值。

備註

  • 帳號的 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 狀態核對。