Інтеграція Telegram-ботів і WebApp з платформою

1) Навіщо Telegram в iGaming

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

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

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

💡 Важливо: не переносьте «ігрову механіку на гроші» всередину бота. Використовуйте Telegram як компаньйон-канал: повідомлення, профіль, КУС/статуси, турніри/лідерборди, промо, саппорт, реферальні флоу. Грошові операції - у веб-кабінеті/додатку з повноцінним 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 T.

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 username (nullable)'+ атрибути згоди (marketing/notifications).

Стратегії link/unlink:

Новий користувач → створюємо спрощений профіль, просимо підтвердити телефон/е-mail в кабінеті.
Існуючий → deep-link '/start link:'або WebApp з'start _ param', відкриваємо модал для прив'язки.
Unlink - через налаштування, миттєво відкликаємо ability на пуш-повідомлення.

5) Вебхук бота: безпека і стійкість

HTTPS + фіксований домен, mTLS (по можливості) і валідний secret path ('/bot/< token>'), або власний секрет в заголовку.

Обмеження IP: whitelisting Telegram IP (якщо інфраструктура дозволяє), WAF-правила.

Ідемпотентність: зберігайте'update _ id', обробляйте рівно один раз.

Ретраї: Telegram повторює при 5хх/тайм-ауті - тримайте обробку <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/< bot>? start = '( до ~ 64 байт корисних даних в base64url).

Використовуйте payload як одноразовий nonce для:

реферальних кампаній ('aff _ id','campaign _ id','click _ id'), продовження незавершеного флоу (KYC step, місія, турнір), зв'язування акаунта.
Зберігайте відповідність'nonce , робіть 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 → показуємо баланси, статуси КУС/ліміти відповідальної гри, історію транзакцій (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; зв'язуйте з трейсами платформи.

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, черги і спостережуваність - і отримаєте швидкий, безпечний і вимірний канал зростання і утримання.