Справочник 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 введите data.verify_code на телефоне; для Telegram отправьте полученный код в /auth/code.

  • awaiting_password

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

  • authorized

    Авторизация завершена. Автоматический запуск подключения не означает готовность: перед отправкой проверьте runtime_status.

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

Подсостояния авторизации Passkey в WhatsApp

  • passkey_required

    QR-поток требует дополнительного credential Passkey. Создайте публичную сессию авторизации.

  • passkey_pending

    Challenge Passkey выдан; ожидается завершение размещённого authorize_url или отправка ответа WebAuthn.

  • passkey_confirmation

    Провайдер требует явного подтверждения после проверки credential.

  • passkey_confirmation_sent

    Запрос подтверждения отправлен; продолжайте опрашивать состояние аутентификации.

  • authorized

    Авторизация завершена. Автоматический запуск подключения не означает готовность: перед отправкой проверьте runtime_status.

  • failed

    Поток завершился ошибкой; причина — в last_error. Для повтора запустите новый поток.

Переходы
1
passkey_required→passkey_pending

Отправьте сериализованный credential WebAuthn через размещённую страницу или POST /auth/passkey-response.

2
passkey_pending→passkey_confirmation

Провайдер просит пользователя подтвердить операцию Passkey.

3
passkey_confirmation→passkey_confirmation_sent

POST /auth/passkey-confirm отправляет подтверждение пользователя.

4
passkey_pending→authorized

Провайдер принимает credential без дополнительного подтверждения.

5
passkey_confirmation_sent→authorized

Провайдер принимает подтверждённый credential.

6
passkey_*→failed

Провайдер отклоняет или не может завершить поток Passkey.

Машина состояний 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 явно запрашивает запуск; вызывайте его только если фактический runtime_status этого требует, и обрабатывайте operation_status из ответа.
  • Пока аккаунт авторизован, 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 сообщает наблюдаемые провайдером изменения авторизации или runtime, но не гарантируется для каждого запрошенного перехода. После действий и переподключений сверяйте webhook-состояние через GET /v1/accounts/{account_id} или POST /runtime/refresh.