← API Reference
Getting Started

Account lifecycle

An account carries three independent states: status (the business switch you set), the authentication state returned by GET /v1/accounts/{id}/auth, and runtime_status (the live connection). Webhook payloads expose the last two as auth_status and runtime_status — note the REST account object itself has no field named auth_status.

Authentication state machine

  • pending_auth

    Initial state after account creation; no flow started yet.

  • awaiting_qr_scan

    A QR flow is active; auth_payload carries the QR content to render.

  • awaiting_code

    A code flow is active; for WhatsApp the verify_code in auth_payload is entered on the phone.

  • awaiting_password

    The provider requires a two-factor password after the code step.

  • authorized

    Authentication complete. The runtime is started automatically.

  • failed

    The flow failed; last_error carries the reason. Start a new flow to retry.

Transitions
1
pending_auth→awaiting_qr_scan

POST /auth/qr/start begins a QR flow.

2
pending_auth→awaiting_code

POST /auth/start begins a verification-code flow.

3
awaiting_code→awaiting_password

The provider demands a two-factor password.

4
awaiting_qr_scan→authorized

The QR scan is confirmed by the provider.

5
awaiting_code→authorized

The code (or WhatsApp pairing) is accepted.

6
awaiting_password→authorized

The password is accepted.

7
authorized→pending_auth

The provider invalidates the session — an account.auth.required event fires and a new flow is needed.

8
awaiting_*→failed

The provider reports failure at any waiting step (account.auth.failed event).

9
awaiting_*→pending_auth

POST /auth/cancel abandons the active flow.

Runtime state machine

  • unknown

    The initial state after account creation, and whenever the platform has no fresh report from the provider — call /runtime/refresh to resync.

  • starting

    A start is in progress; the provider is bringing the session online.

  • running

    Connected and able to send and receive.

  • reconnecting

    The connection dropped and an automatic or manual reconnect is in progress.

  • disconnected

    The provider reported the session offline; reconnect or start to recover.

  • stopping

    A stop is in progress.

  • stopped

    Not connected. The state after a stop.

  • error

    The runtime hit an unrecoverable error; last_error carries the reason.

Transitions
1
unknown→starting

Automatic start after authorization succeeds.

2
stopped→starting

An explicit POST /runtime/start.

3
starting→running

The provider session comes online (account.started event).

4
running→reconnecting

The connection drops, or POST /runtime/reconnect is called.

5
reconnecting→running

The connection is re-established.

6
running→disconnected

The provider reports the session offline (account.status.updated event).

7
disconnected→running

POST /runtime/reconnect or /runtime/start brings it back.

8
running→stopping

POST /runtime/stop begins a graceful stop.

9
stopping→stopped

The stop completes.

10
*→error

An unrecoverable provider error at any point.

11
*→unknown

No fresh provider report; POST /runtime/refresh resyncs the value.

Notes

  • Account.status is yours (a business on/off switch set at creation or via PATCH). The other two are platform-owned and read-only: the auth state via GET /v1/accounts/{id}/auth (its status field), runtime_status on the account object.
  • Successful authorization starts the runtime automatically — calling POST /runtime/start afterwards is a harmless no-op.
  • While authorized, POST /auth/start, /auth/qr/start, and /auth/session are rejected with 409 account_already_authorized. Call POST /auth/cancel first if you really need a fresh flow.
  • An account.auth.required event means the provider invalidated the session: auth falls out of authorized and auth_payload carries the material (such as a new QR) for re-authentication.
  • Every runtime change is pushed as an account.status.updated event carrying both auth_status and runtime_status — keep your local copy in sync from the webhook rather than polling.