はじめに

アカウントライフサイクル

アカウントは独立した 3 つの状態を持ちます：status（あなたが設定するビジネススイッチ）、GET /v1/accounts/{id}/auth が返す認証状態、そして runtime_status（ライブ接続）。webhook ペイロードでは後者 2 つが 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 にあります。再試行するには新しいフローを開始してください。

遷移

pending_auth→awaiting_qr_scan

POST /auth/qr/start が QR フローを開始。

pending_auth→awaiting_code

POST /auth/start が認証コードフローを開始。

awaiting_code→awaiting_password

プロバイダが二要素パスワードを要求。

awaiting_qr_scan→authorized

プロバイダが QR スキャンを確認。

awaiting_code→authorized

認証コード（または WhatsApp のペアリング）が受理される。

awaiting_password→authorized

パスワードが受理される。

authorized→pending_auth

プロバイダがセッションを無効化 — account.auth.required イベントが発火し、新しいフローが必要になります。

awaiting_*→failed

いずれかの待機ステップでプロバイダが失敗を報告（account.auth.failed イベント）。

awaiting_*→pending_auth

POST /auth/cancel が進行中のフローを破棄。

WhatsApp Passkey サブフロー

passkey_required
QR 認証を続けるため、WhatsApp がブラウザの WebAuthn 資格情報を要求しています。
passkey_pending
WebAuthn 資格情報は送信済みで、プロバイダの処理待ちです。
passkey_confirmation
プロバイダがユーザーによる明示的な確認を要求しています。
passkey_confirmation_sent
確認が送信され、プロバイダが認可を完了中です。
authorized
認可は完了しています。接続の自動開始は準備完了を意味しません。送信前に runtime_status を確認してください。
failed
フローが失敗。理由は last_error にあります。再試行するには新しいフローを開始してください。

遷移

passkey_required→passkey_pending

ホスト型ページまたは POST /auth/passkey-response でシリアライズ済み WebAuthn 資格情報を送信します。

passkey_pending→passkey_confirmation

プロバイダが Passkey 操作の確認をユーザーに要求します。

passkey_confirmation→passkey_confirmation_sent

POST /auth/passkey-confirm がユーザー確認を送信します。

passkey_pending→authorized

追加確認なしでプロバイダが資格情報を受理します。

passkey_confirmation_sent→authorized

プロバイダが確認済み資格情報を受理します。

passkey_*→failed

プロバイダが Passkey フローを拒否、または完了できません。

ランタイムステートマシン

unknown
アカウント作成直後の初期状態。プラットフォームにプロバイダからの新しい報告がない間もこの状態になります — /runtime/refresh で再同期してください。
starting
起動処理が進行中。プロバイダがセッションをオンラインにしています。
running
接続済みで、送受信が可能な状態。
reconnecting
接続が切断され、自動または手動の再接続が進行中。
disconnected
プロバイダがセッションのオフラインを報告。reconnect または start で復旧します。
stopping
停止処理が進行中。
stopped
未接続。停止後の状態です。
error
ランタイムが回復不能なエラーに遭遇。理由は last_error にあります。

遷移

unknown→starting

認証成功後の自動起動。

stopped→starting

明示的な POST /runtime/start。

starting→running

プロバイダのセッションがオンラインになる（account.started イベント）。

running→reconnecting

接続が切断される、または POST /runtime/reconnect が呼ばれる。

reconnecting→running

接続が再確立される。

running→disconnected

プロバイダがセッションのオフラインを報告（account.status.updated イベント）。

disconnected→running

POST /runtime/reconnect または /runtime/start で復帰。

running→stopping

POST /runtime/stop がグレースフルな停止を開始。

stopping→stopped

停止が完了。

*→error

任意の時点での回復不能なプロバイダエラー。

*→unknown

プロバイダからの新しい報告がない状態。POST /runtime/refresh で値を再同期します。

注記

Account.status はあなたが管理するもの（作成時または PATCH で設定するビジネス上のオン / オフスイッチ）です。残りの 2 つはプラットフォーム管理の読み取り専用：認証状態は 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 状態を照合してください。