Zapnoty — Авторизация через ботов

Auth через ботов

Авторизация пользователей вашего сайта через ботов Telegram/Max. Пользователь кликает ссылку, подтверждает в боте, автоматически подписывается на уведомления, и вы получаете его данные.

Как это работает

1. Пользователь кликает ссылку бота

2. Бот показывает запрос авторизации с кнопками "Войти" / "Отмена"

3. Пользователь нажимает "Войти" → автоматическая подписка на уведомления + генерация кода

4. Бот отправляет кнопку "Перейти на сайт" → callback_url?code=CODE

5. Ваш сервер вызывает POST /v1/auth/verify → получает данные

Настройка

В дашборде проекта перейдите в Settings → Auth и задайте Callback URL и Origin URL.

Статические ссылки

Простой вариант — постоянная ссылка. Получите через API или в дашборде:

GET /v1/auth/link

// Response:

{

"telegram_link": "https://t.me/YourBot?start=auth_my-app",

"max_link": "https://max.ru/YourBot?start=auth_my-app",

"configured": true

}

Статическая ссылка авторизации (формат auth_<slug>) работает только если у проекта настроен callback URL (Settings → Auth). Без него бот ответит «Авторизация для этого проекта не настроена». Поле configured в ответе показывает, готов ли проект к авторизации.

Подписка ≠ авторизация

Если вам нужна просто подписка на уведомления (без входа пользователя на сайт) — используйте отдельный механизм: ссылку proj_<slug> из GET /v1/subscribe-link. Она не требует настройки callback и работает всегда. Префикс auth_ — это авторизация (вход с возвратом данных пользователя), префикс proj_ — простая подписка. Подробнее — в разделе Подписчики .

API-сессии (с state)

Для передачи state (например, ID браузерной сессии) создайте сессию через API:

POST /v1/auth/session

{

"state": "browser_session_abc", // ваш токен — вернётся обратно

"redirect_uri": "https://you.com/cb" // опц., должен быть в allowlist проекта

}

// Response — одна сессия, ссылки сразу на оба мессенджера:

{

"session_id": "aBcDeFgH12345678",

"telegram_link": "https://t.me/YourBot?start=auths_aBcDeFgH12345678",

"max_link": "https://max.ru/YourBot?start=auths_aBcDeFgH12345678",

"expires_in": 1800

}

state — 1–128 символов, печатаемый ASCII без пробелов и символов < > &. Кладите туда opaque-токен (не email/телефон) — он вернётся в auth.completed и в /v1/auth/verify.
redirect_uri — опционально. Для notification-only flow (получение результата через webhook auth.completed) callback не нужен вообще. Если задан — должен точно совпадать с URL из allowlist проекта.
Сессия живёт 30 минут (expires_in: 1800). Обычно пользователь проходит привязку сразу: открыл ссылку → бот → подтвердил. 30 минут — запас на случай, если отвлёкся. Если ссылка всё же истекла — бот при /start ответит сообщением «срок истёк»; просто создайте новую сессию. Поллинг статуса завершайте по expires_in.

Верификация кода

После подтверждения пользователь попадает на callback_url?code=CODE. Верифицируйте код:

POST /v1/auth/verify

{ "code": "aBcDeFgH..." } // code одноразовый, TTL 1800 c

// Response:

{

"channel": "telegram",

"first_name": "John",

"username": "johndoe", // без @, "" если нет

"avatar_url": null,

"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",

"lang": "ru",

"tags": [],

"state": "browser_session_abc", // ваш токен, null если не передавали

"auth_time": "2026-05-21T12:00:00+00:00"

}

QR/Polling (кросс-девайс)

Для авторизации на десктопе через мобильного бота: создайте сессию, покажите QR-код со ссылкой, и поллите статус. Когда пользователь подтвердит авторизацию на телефоне, вы получите code. Интервал polling: 2-3 секунды. Код одноразовый — после получения status=completed повторный запрос вернёт expired.

GET /v1/auth/session/{session_id}/status

// Pending:

{ "status": "pending" }

// Completed:

{ "status": "completed", "code": "aBcDeFgH..." }

Как получить результат: три способа

После того как пользователь нажал ссылку и подтвердил вход в боте, результат можно получить одним из трёх способов:

Webhook auth.completed — приходит всегда. В payload — subscriber_id, state (ваш токен) и данные подписчика. Самый простой путь для backend-интеграции: callback-сервис не нужен.
Поллинг GET /v1/auth/session/{session_id}/status — при status: "completed" возвращается code, затем POST /v1/auth/verify.
Redirect с кодом — если у проекта настроен callback URL.

Callback URL и redirect

Zapnoty не редиректит браузер автоматически. Если у проекта задан callback URL, бот после подтверждения показывает пользователю кнопку «перейти на сайт» со ссылкой:

{callback_url}?code=<code>&state=<urlencoded state>

code — всегда; state — если передавали в /v1/auth/session.
callback URL берётся из redirect_uri запроса /v1/auth/session либо из настроек проекта. Любой используемый URL обязан быть в allowlist проекта (настройки проекта → авторизация) — точное совпадение, защита от open-redirect.
Если callback URL не настроен — flow notification-only: бот просто показывает сообщение об успехе, а вы получаете данные через webhook auth.completed.

Кастомизация текстов авторизации

Текст сообщения авторизации и подпись кнопки настраиваются через PUT /v1/sender (поля auth_text и auth_button_text, мультиязычные {ru, en}). auth_text должен содержать переменную {{url}} (≤500 символов), auth_button_text — ≤32 символа. Управление проектом.