Интеграция Telegram-ботов и WebApp с платформой

1) Зачем Telegram в iGaming

Охват и ретеншн: быстрые пуш-диалоги (уведомления о турнирах/миссиях, статусах, промо).

Лёгкий вход: SSO через Telegram Login Widget / WebApp `initData` без пароля.

Мини-клиент: WebApp внутри Telegram с нативной темой/кнопками и безопасной передачей контекста.

💡 Важно: не переносите «игровую механику на деньги» внутрь бота. Используйте Telegram как компаньон-канал: уведомления, профиль, KYC/статусы, турниры/лидерборды, промо, саппорт, реферальные флоу. Денежные операции — в веб-кабинете/приложении с полноценным KYC/AML и PSP.

2) Архитектура интеграции

Компоненты:

1. Telegram Bot (Bot API): обработка апдейтов (webhook), команды/клавиатуры, deep-links `/start payload`.

2. Telegram WebApp (TWA): Web-страница внутри Telegram (in-app WebView), получает `initData` и интегрируется с UI Telegram.

3. Auth/SSO шлюз платформы: верификация подписи `initData`/Login Widget, выпуск краткоживущего platform JWT.

4. Backend API платформы: профиль/кошелёк/турниры/миссии/аффилиаты/саппорт.

5. Event bus: нотификации (Kafka/Redis Streams) → отправка сообщений ботом.

6. Observability & Security: WAF, mTLS к вебхуку, rate-limit, аудит, алертинг.

Поток SSO (коротко):

Telegram (WebApp/Login) → `initData`/auth-payload → Auth шлюз проверяет HMAC → выдаёт JWT (5–15 мин) → WebApp/бот вызывает API платформы с JWT.

3) Способы авторизации

A) Telegram WebApp (`window.Telegram.WebApp`)

Телеграм подставляет `initData` в WebApp. Вы его подписываете на сервере HMAC-SHA256 с ключом = bot token.

При успехе выпускаете короткий JWT и (если нужно) связываете Telegram-аккаунт с уже существующим профилем.

Псевдокод проверки `initData`:

python def verify_init_data(init_data: str, bot_token: str) -> dict:
init_data — строка query-like "key1=..&key2=.."
data = parse_qs(init_data)
hash_provided = data.pop('hash')[0]
check_string = '\n'.join([f"{k}={v[0]}" for k in sorted(data.keys())])
secret = hmac.new(b"WebAppData", bot_token.encode(), 'sha256').digest()
calc = hmac.new(secret, check_string.encode(), 'sha256').hexdigest()
assert hmac.compare_digest(calc, hash_provided)
проверяем свежесть auth_date (например, ≤ 10 мин)
assert now() - int(data['auth_date'][0]) < 600 return data

B) Telegram Login Widget (внешняя страница)

Виджет даёт `id, first_name, auth_date, hash`. Проверка аналогична (`"Telegram Login" + bot_token`).

Подходит, если вы не используете WebApp, а входите в обычный веб-кабинет.

4) Связывание аккаунта и модель идентичности

Первичный ключ: `telegram_user_id` (`from.id`).

Создаём запись связывания: `platform_user_id ↔ telegram_user_id ↔ chat_id ↔ username (nullable)` + атрибуты согласия (marketing/notifications).

Стратегии link/unlink:

Новый пользователь → создаём упрощённый профиль, просим подтвердить телефон/e-mail в кабинете.
Существующий → deep-link `/start link:` или WebApp с `start_param`, открываем модал для привязки.
Unlink — через настройки, мгновенно отзываем ability на пуш-уведомления.

5) Вебхук бота: безопасность и устойчивость

HTTPS + фиксированный домен, mTLS (по возможности) и валидный secret path (`/bot/`), либо собственный секрет в заголовке.

Ограничение IP: whitelisting Telegram IP (если инфраструктура позволяет), WAF-правила.

Идемпотентность: сохраняйте `update_id`, обрабатывайте ровно один раз.

Ретраи: Telegram повторяет при 5xx/тайм-ауте — держите обработку < 1 с, тяжёлое — в очередь.

Rate-limits: локальные токен-бакеты на отправку сообщений (Telegram ограничивает спам), очереди для массовых рассылок.

Пример каркаса обработчика:

python
@app.post("/telegram/webhook")
def on_update(u: Update):
if seen(u.update_id): return "ok"
queue.publish("tg.updates", u.json()) # async consume mark_seen(u.update_id)
return "ok"

6) Deep-links, старт-параметры и рефералка

Ссылка вида: `t.me/?start=` (до ~64 байт полезных данных в base64url).

Используйте payload как одноразовый nonce для:

реферальных кампаний (`aff_id`, `campaign_id`, `click_id`), продолжения незавершённого флоу (KYC step, миссия, турнир), связывания аккаунта.
Храните соответствие `nonce → intended_action → expires_at`, делайте single-use.
Для WebApp — `t.me//app?startapp=` (получите в `initData.start_param`).

7) Telegram WebApp: UX и интеграция

Фичи TWA:

Тема (`themeParams`), mainButton/secondaryButton, BackButton, `HapticFeedback`, `expand()`, `viewport`.
Двусторонний обмен: `Telegram.WebApp.sendData()` → прилетит в апдейт бота; либо WebApp вызывает ваш Backend API напрямую с полученным JWT.

Рекомендации:

Светлая/тёмная тема автоматически из `themeParams`.
Не храните `initData` в браузере дольше 10 мин; обновляйте JWT refresh-эндпоинтом (по серверной сессии).
Обработайте закрытие WebApp (например, отправьте подтверждение действия в чат).
Уважайте ограничения WebView: CSP, только https, размеры, без всплывающих окон.

Мини-пример инициализации:

js const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
const initData = tg.initData; // отправьте на свой backend для обмена на JWT tg.MainButton.setText('Продолжить').show().onClick(() => submit());

8) Типовые флоу

Профиль/кошелёк (просмотр)

Пользователь открывает WebApp → верификация `initData` → выдаём JWT → показываем балансы, статусы KYC/лимиты ответственной игры, историю транзакций (read-only).

Турниры/миссии

В TWA показываем лидерборды и прогресс миссий (реал-тайм, короткий polling/WS через бэкенд).

Кнопки: «Участвовать», «Поделиться» (deep-link для друзей), «Уведомить за 5 мин до старта».

Уведомления

События платформы → event bus → consumer формирует текст/инлайн-клавиатуру → `sendMessage` с `inline_keyboard` (ссылка «Открыть WebApp» или deep-link).

Поддерживайте opt-in/opt-out на типы уведомлений (турниры, вывод, бонусы).

Саппорт

Быстрый тикет/FAQ в WebApp + кнопка «Открыть чат с оператором».

Верифицируйте пользователя (SSO), подтягивайте контекст последней сессии/депозита.

9) Платежные и комплаенс-аспекты

Денежные транзакции (депозиты/выводы) — в веб-кабинет, открытый из бота (кнопка URL) или из WebApp (кнопка «Перейти в кабинет»).

Внутри TWA разрешите безопасные операции read-only и «лёгкие» действия (привязки, промо-активации, турниры).

Приватность: не выводите PII в чат; показывайте его только внутри WebApp (https, авторизация).

Логи согласий, политика хранения, «право на удаление» — в профиле.

10) Антифрод и защита

Проверка свежести `auth_date` и таймзоны/ASN аномалий.

Rate-limit по `telegram_user_id` и IP на чувствительные операции (активация промо, реферал).

Защита deep-links: одноразовые токены, короткий TTL, привязка к юзеру/чату.

Для массовых рассылок — batch + jitter, проверка «остудить» на жалобы/блокировки.

Верификация файлов/медиа из чатов (если вы принимаете документы): скачивайте через Bot API по `file_id`, проверяйте тип/размер/вирусы, храните в комплаенс-контуре.

11) Наблюдаемость, алерты, лимиты

Метрики:

`tg_webhook_latency`, `webhook_5xx`, `queue_lag`, `send_rate`, `flood_wait_hits`.
SLI WebApp: `auth_verify_success`, `jwt_issue_latency_p95`, `api_4xx/5xx`, `leadboard_rtt`.
Конверсия: открытие → авторизация → целевое действие (миссия/турнир/возврат в кабинет).

Алерты:

Ошибка проверки подписи > X% за 5 мин.
`FloodWait`/429 при отправке сообщений.
Рост `deep_link_reuse` или ошибок одноразовых токенов.

Логи: JSON с `trace_id`, `telegram_user_id` (псевдоним), без PII; связывайте с трейcами платформы.

12) Контракты API (эскизы)

Обмен `initData` на JWT

http
POST /v1/tg/exchange
{ "init_data": "<string>" }
→ 200 { "jwt":"<short-lived>", "expires_in":900 }

Профиль

http
GET /v1/tg/me
Authorization: Bearer <jwt>
→ 200 { "user_id":"u_123", "balances":[...], "kyc":{"level":"basic"} }

Подписки на уведомления

http
POST /v1/tg/consents
{ "promotions": true, "tournaments": true, "payouts": true }

Рассылка (внутренний сервис)

json
{
"template":"tournament_start",  "vars":{"name":"Halloween Sprint","starts_in":"5m"},  "targets":[{"chat_id":12345,"user_id":"u_123"}]
}

13) Примеры UI в боте

Инлайн-клавиатура «турнир»

json
{
"inline_keyboard": [
[{"text":"Открыть лидерборд","web_app":{"url":"https://twa.example/contest?id=october"}}],   [{"text":"Правила","url":"https://brand.com/contests/october/rules"}]
]
}

Reply-клавиатура «Главное меню»

Профиль

Турниры и миссии
Бонусы и промо
Поддержка

14) Масштаб и отказоустойчивость

Webhook → очередь → воркеры (stateless); горизонтальный масштаб.

Храните «состояние диалога» в Redis/DB (finite state machine per `chat_id`).

Резервный механизм getUpdates (long polling) только для дебага/фолбэка.

Ограничьте скорость отправки (`messages/sec`) и размер бранч-рассылок; планировщик волн.

DR: бэкап токенов/секретов, вторичный webhook endpoint, сценарий «быстрого переключения».

15) Чек-лист прод-готовности

Webhook HTTPS, секрет/мТLS, retry-безопасность, идемпотентность `update_id`.
Проверка подписи `initData`/Login Widget, окно свежести, обмен на короткий JWT.
Link/unlink аккаунта, хранение `telegram_user_id`/`chat_id`, согласия на уведомления.
Deep-links/`startapp` только одноразовые, TTL и аудит.
WebApp: тема, кнопки, back, refresh JWT; CSP, https, без PII в URL.
Антифрод: rate-limit, ASN/прокси-сигналы, защита рефералок.
Рассылки: очереди, batch+jitter, мониторинг FloodWait/429.
Наблюдаемость: метрики webhook/TWA/конверсии, алерты.
Документация UX/ограничений, политика приватности, DPA с Telegram как каналом.
Runbook’и: падение webhook, всплеск дубликатов, массовый FloodWait, отказ TWA.

Резюме

Интеграция с Telegram — это не «ещё один бот», а полноценный канал с безопасным SSO (проверка `initData`/Login), аккуратным UX WebApp и надёжной серверной обработкой апдейтов. Держите денежные операции в основном приложении, а в Telegram — сильные компаньон-сценарии: профиль, турниры, миссии, нотификации, саппорт и рефералка. Добавьте одноразовые deep-links, короткоживущие JWT, очереди и наблюдаемость — и получите быстрый, безопасный и измеримый канал роста и удержания.