Руководство August 12, 2026

Восстановление runtime для messaging account: refresh, reconnect, start или повторная авторизация?

Если messaging account в UnifyPort перестал получать сообщения, не начинайте с повторного входа. Сначала прочитайте состояние авторизации и runtime_status: обновите неизвестное или устаревшее состояние, переподключите авторизованный аккаунт с неисправным соединением, запустите остановленный runtime и выполняйте повторную авторизацию только тогда, когда этого требует состояние auth или событие account.auth.required.

Главное

status, состояние авторизации и runtime_status — три независимых параметра.
После успешной авторизации runtime обычно запускается автоматически.
POST /runtime/refresh синхронизирует состояние, но не перезапускает соединение.
POST /runtime/reconnect перестраивает проблемное соединение, сохраняя авторизацию.
Webhook дает сигнал; результат действия нужно сверять через чтение аккаунта или refresh.

Разделяйте три уровня состояния

Документация жизненного цикла аккаунта определяет три уровня:

status — бизнес-переключатель, управляемый workspace.
Состояние авторизации возвращает GET /v1/accounts/{account_id}/auth: pending_auth, awaiting_qr_scan, awaiting_code, awaiting_password, authorized или failed.
runtime_status описывает живое подключение. Нормализованные значения: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error.

Такое разделение предотвращает две типичные ошибки: запрос нового QR-кода для аккаунта, который все еще authorized, и бесконечные попытки reconnect, когда провайдер действительно аннулировал сессию.

Если вы расследуете платформенный инцидент или проверку аккаунта, сначала используйте чек-лист реагирования на WhatsApp Account Under Review. Он помогает разделить сбой платформы, применение правил, проблему runtime и отказ webhook-consumer.

Таблица решений: refresh, reconnect, start или авторизация

Наблюдение	Первое действие	Причина
`runtime_status: unknown`	Refresh	Сначала синхронизируйте актуальное состояние провайдера.
`running`, но соединение подтвержденно неисправно	Reconnect	Перестройте соединение, сохранив текущую авторизацию.
`disconnected`, auth — `authorized`	Reconnect, затем сверка	Авторизация цела, отключен runtime.
`stopped`, аккаунт должен быть онлайн	Start	Остановленный runtime нужно явно запустить.
`starting`, `stopping` или `reconnecting`	Сначала сверка	Действие уже выполняется.
Auth — `pending_auth`, `awaiting_*` или `failed`	Продолжить подходящий auth flow	Runtime-команды не заменяют действия пользователя.
Получено `account.auth.required`	Авторизация по `auth_payload`	Существующая сессия требует действий пользователя.
`runtime_status: error`	Refresh и анализ контекста ошибки	Не у всех ошибок одинаковая причина.

Reconnect endpoint предназначен для ситуации, когда аккаунт существует и авторизован, но его live-соединение неисправно. Start endpoint управляет runtime, а не авторизацией.

Реализуйте восстановление по порядку

1. Читайте аккаунт и auth одновременно

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0 \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0/auth \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

Объект аккаунта содержит runtime_status. Ресурс auth содержит собственный status, а также может содержать auth_payload или last_error. Не выводите состояние авторизации только из runtime.

2. Для unknown сначала вызывайте refresh

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/refresh \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Refresh синхронизирует состояние провайдера и возвращает нормализованный runtime_status. Он также подходит для сверки после start, reconnect или auth-действия, но не заменяет webhook-consumer и хранилище сообщений.

3. Reconnect — только при действующей авторизации

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/reconnect \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Немедленный результат может вернуть reconnecting. Это состояние выполнения, а не доказательство восстановления потока сообщений. После него требуется сверка.

4. Для stopped вызывайте start

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/start \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Успешная авторизация обычно запускает runtime автоматически. Поэтому повторный вход не должен быть обязательным условием для каждого start.

5. Повторная авторизация — только по данным auth

Событие account.auth.required может нести auth_status, runtime_status и зависящие от провайдера данные в auth_payload: QR-код, URL, PIN или код подтверждения. Покажите владельцу аккаунта только нужный шаг и не записывайте материалы сессии в журналы.

Webhook как сигнал, API как проверка

Подпишитесь на account.status.updated, account.started, account.auth.required, account.auth.succeeded и account.auth.failed либо используйте subscribed_events: ["*"]. Публичные payload описаны в каталоге стандартных событий.

account.status.updated сообщает наблюдаемое провайдером изменение, но не гарантирован для каждого запрошенного перехода. После reconnect, start или auth-действия сверяйте состояние через чтение аккаунта или refresh. Перед обработкой проверяйте подпись; руководство по HMAC, защите от повторной доставки и retry описывает контракт подписи raw body.

прочитать auth и runtime_status
если auth требует пользователя: выполнить подходящий auth flow
иначе если unknown: refresh
иначе если disconnected: reconnect
иначе если stopped: start
иначе если действие выполняется: сверить состояние
иначе если running: ничего не менять
иначе: refresh и эскалация с контекстом ошибки

Ограничения

Восстановленный runtime не доказывает исправность webhook endpoint, очереди, базы данных или последующей автоматизации. Если аккаунт running, но приложение не видит сообщения, отдельно проверьте доставку webhook и consumer.

Reconnect также не гарантирует повтор истории. В UnifyPort нет REST API для чтения истории сообщений и гарантированного воспроизведения пропущенных payload. WhatsApp может отправить ограниченную best-effort синхронизацию после запуска или переподключения, но это не полный архив. Сохраняйте входящие события при получении.

FAQ

При `runtime_status: disconnected` нужен новый QR-код?

Не обязательно. Сначала проверьте auth. Если он остается authorized, используйте reconnect. Новый auth flow нужен только по состоянию авторизации или событию account.auth.required.

Чем refresh отличается от reconnect?

Refresh читает и нормализует актуальное состояние. Reconnect активно перестраивает неисправное соединение.

Нужно ли вызывать start после каждой успешной авторизации?

Обычно нет. Runtime запускается автоматически; start нужен только тогда, когда наблюдаемое состояние этого требует.

Что проверить при running без входящих сообщений?

Статус webhook, проверку подписи, HTTP-подтверждение, retry, очередь и сохранение. Исправное соединение и исправный consumer — разные условия.

Следующий шаг

Реализуйте таблицу решений по руководству жизненного цикла аккаунта и добавьте Refresh runtime state в эксплуатационный runbook.

Официальные источники

Документация UnifyPort проверена 12 августа 2026 года: