← API リファレンス
はじめに

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

アカウントは独立した 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 では 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

    プロバイダがセッションのオフラインを報告。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 で値を再同期します。

注記

  • Account.status はあなたが管理するもの（作成時または PATCH で設定するビジネス上のオン / オフスイッチ）です。残りの 2 つはプラットフォーム管理の読み取り専用：認証状態は 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 など）が入ります。
  • ランタイムの変化はすべて、auth_status と runtime_status の両方を含む account.status.updated イベントとしてプッシュされます — ポーリングではなく webhook からローカルコピーを同期してください。