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

    Waiting for user action. For WhatsApp, enter data.verify_code on the phone; for Telegram, submit the received code to /auth/code.

  • awaiting_password

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

  • authorized

    Authorization is complete. An automatic connection start does not mean it is ready; check runtime_status before sending.

  • 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.

WhatsApp Passkey sub-flow

  • passkey_required

    WhatsApp requires a browser WebAuthn credential before QR authorization can continue.

  • passkey_pending

    The WebAuthn credential was submitted and is awaiting provider processing.

  • passkey_confirmation

    The provider requires an explicit user confirmation.

  • passkey_confirmation_sent

    The confirmation was sent and the provider is completing authorization.

  • authorized

    Authorization is complete. An automatic connection start does not mean it is ready; check runtime_status before sending.

  • failed

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

Transitions
1
passkey_required→passkey_pending

Submit the serialized WebAuthn credential through the hosted page or POST /auth/passkey-response.

2
passkey_pending→passkey_confirmation

The provider asks the user to confirm the Passkey operation.

3
passkey_confirmation→passkey_confirmation_sent

POST /auth/passkey-confirm sends the user confirmation.

4
passkey_pending→authorized

The provider accepts the credential without an extra confirmation step.

5
passkey_confirmation_sent→authorized

The provider accepts the confirmed credential.

6
passkey_*→failed

The provider rejects or cannot complete the Passkey 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 normally starts the runtime automatically. POST /runtime/start explicitly requests a start; call it only when the observed runtime_status still requires one, and handle the returned operation status.
  • 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 current authorization needs user action. It can occur during first-time authorization or reauthorization; do not infer a previously authorized or invalidated session from this event alone. Read data.auth_status for the waiting step and data.auth_payload for the available authorization material.
  • account.status.updated reports provider-observed auth or runtime changes, but it is not guaranteed for every requested transition. Reconcile webhook state with GET /v1/accounts/{account_id} or POST /runtime/refresh after actions and reconnects.