← Справочник 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 verify_code из auth_payload вводится на телефоне.

  • awaiting_password

    Провайдер требует двухфакторный пароль после шага с кодом.

  • authorized

    Аутентификация завершена. Runtime запускается автоматически.

  • 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 прерывает активный поток.

Машина состояний runtime

  • unknown

    Начальное состояние после создания аккаунта, а также когда у платформы нет свежего отчёта от провайдера — вызовите /runtime/refresh для ресинхронизации.

  • starting

    Идёт запуск; провайдер выводит сессию в онлайн.

  • running

    Подключено; можно отправлять и получать сообщения.

  • reconnecting

    Соединение оборвалось, идёт автоматическое или ручное переподключение.

  • disconnected

    Провайдер сообщил, что сессия офлайн; для восстановления выполните reconnect или start.

  • stopping

    Идёт остановка.

  • stopped

    Не подключено. Состояние после остановки.

  • error

    Runtime столкнулся с неустранимой ошибкой; причина — в 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). Два других принадлежат платформе и доступны только для чтения: состояние аутентификации — через GET /v1/accounts/{id}/auth (его поле status), runtime_status — на объекте аккаунта.
  • Успешная авторизация запускает runtime автоматически — последующий вызов POST /runtime/start безвреден и является no-op.
  • Пока аккаунт авторизован, POST /auth/start, /auth/qr/start и /auth/session отклоняются с 409 account_already_authorized. Если новый поток действительно нужен, сначала вызовите POST /auth/cancel.
  • Событие account.auth.required означает, что провайдер аннулировал сессию: состояние аутентификации выходит из authorized, а auth_payload несёт материал (например, новый QR) для повторной аутентификации.
  • Каждое изменение runtime приходит как событие account.status.updated с auth_status и runtime_status — синхронизируйте локальную копию из webhook, а не опросом.