Integracja botów Telegram i WebApp z platformą

1) Dlaczego Telegram w iGaming

Zasięg i retencja: szybkie dialogi push (powiadomienia o turnieju/misji, statusy, promocje).

Łatwe logowanie: SSO przez Telegram Login Widget/WebApp 'initData' bez hasła.

Mini-klient: WebApp wewnątrz Telegram z rodzimym motywem/przyciskami i bezpiecznym transferem kontekstowym.

💡 Ważne: nie przenosić „mechaniki gry za pieniądze” wewnątrz bot. Użyj Telegram jako kanał towarzysz: powiadomienia, profil, CUS/statusy, turnieje/liderów, promo, wsparcie, przepływ poleceń. Transakcje pieniężne - w szafce internetowej/aplikacji z pełnym KYC/AML i PSP.

2) Architektura integracji

Komponenty:

1. Telegram Bot (Bot API): aktualizacje przetwarzania (webhook), polecenia/klawiatury, głębokie linki '/start payload '.

2. Telegram WebApp (TWA): Strona internetowa wewnątrz Telegramu (WebView), otrzymuje 'initData' i integruje się z interfejsem Telegram.

3. Brama platformy Auth/SSO: weryfikacja podpisu 'initData '/Login Widget, wydanie krótkotrwałej platformy JWT.

4. Platformy API backend: profil/portfel/turnieje/misje/partnerzy/wsparcie.

5. Autobus zdarzeń: powiadomienia (Kafka/Redis Streams) → wysyłanie wiadomości bot.

6. Obserwacja i bezpieczeństwo: WAF, mTLS do webhook, rate-limit, audyt, alert.

Przepływ SSO (krótki):

Telegram (WebApp/Login) → 'initData '/auth-payload → Auth brama sprawdza HMAC → wydania JWT (5-15 minut) → WebApp/bot call platform API z JWT.

3) Metody autoryzacji

A) Telegram WebApp ('okno. Telegram. WebApp ')

Telegram zastępuje 'initData' in WebApp. Podpisz go na serwerze HMAC-SHA256 z klawiszem = bot token.

Jeśli się uda, zwolnij krótki JWT i (w razie potrzeby) powiąż konto Telegram z istniejącym profilem.

Kod pseudo walidacji „initData”:

python def verify_init_data (init_data: str, bot_token: str) -> dict:
init_data - ciąg pytań typu „key1 =.. & key2 =”..
dane = parse_qs (init_data)
hash_provided = dane. pop („hash”) [0]
check_string = '\n' .join ([f „{k} = {v [0]}” dla k w sortowanym (dane. klucze ()))
secret = hmac. nowy (b „WebAppData”, bot_token. kod (), „sha256”). trawienie ()
calc = hmac. nowy (tajemnica, check_string. kod (), „sha256”). heksdigest ()
assert hmac. compare_digest (calc, hash_provided)
sprawdzić świeżość auth_date (na przykład, ≤ 10 minut)
assert now () - int (data ['auth _ date'] [0]) <600 return data

B) Widget logowania telegramowego (strona zewnętrzna)

Widget daje 'id, first_name, auth_date, hash'. Czek jest podobny ('Telegram Login' + bot_token').

Odpowiednie, jeśli nie używasz WebApp, ale wprowadź zwykłą szafkę internetową.

4) Powiązanie konta i model tożsamości

Klucz podstawowy: 'telegram _ user _ id' (' from. id').

Tworzymy rekord wiązania: 'platforma _ user _ id „,” platform _ user _ id „,” platforma _ user _ id „,” platform _ user _ id „,” platform _ user _ id „,” platform _ user _ user _ id „,” platform _ user _ user _ id „,” platform _ user _ user _ id _ user _ id _ id _ user _ id _ id _ id _ id _ id _ id _ _ id _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

Strategie link/unlink:

Nowy użytkownik → utwórz uproszczony profil, potwierdź telefon/e-mail w biurze.
Istniejące głębokie łącze → '/start link: 'lub WebApp z' start _ param ', otwórz modal do wiązania.
Odłączanie - poprzez ustawienia natychmiast odwołujemy możliwość wciskania powiadomień.

5) Bot Webhook: Bezpieczeństwo i zrównoważony rozwój

HTTPS + domeny stałe, mTLS (jeśli to możliwe) i prawidłowa ścieżka tajna ('/bot/< token> ') lub jej własny sekret w nagłówku.

Ograniczenie IP: whitelisting Telegram IP (jeśli pozwala na to infrastruktura), zasady WAF.

Idempotence: zachowaj 'update _ id', przetwarzaj dokładnie raz.

Retrai: Telegram powtarza się w 5xx/timeout - przetwarzaj <1 s, ciężki - w kolejce.

Limity stawek: lokalne wiadra do wysyłania wiadomości (Telegram limits spam), kolejki do przesyłek masowych.

Przykładowe ramy obsługi:

python
@ app. post („/telegram/webhook ”)
def on_update (u: Aktualizacja):
jeśli widziano (u. update_id): zwrot „ok”
kolejki. publikacja ("tg. aktualizacje", u. json ()) # async consume mark_seen (u. update_id)
zwrot „ok”

6) Głębokie połączenia, parametry rozruchu i polecenie

Wyświetl odniesienie: 't. me/< bot>? start = '(do ~ 64 bajtów ładunku w base64url).

Użyj ładunku jako jednorazowego nonce dla:

kampanie polecające ('aff _ id',' campaign _ id', 'click _ id'), kontynuacja niedokończonego przepływu (KYC step, mission, turniej), powiązanie konta.
Zachować zgodność 'nonce → intended_action → expires_at', zrobić jednorazowego użytku.
Dla WebApp - 't. me/< bot >/app? startapp = '(get in' initData. start_param').

7) Telegram WebApp: UX i integracja

Funkcja TWA:

Тема ('themeParams'), mainButton/Second, BackButton,' HapticFeedback ',' expand () ',' viewport '.
Wymiana dwustronna: "Telegram. WebApp. Data () '→ pojawi się w aktualizacji bot; lub WebApp wywołuje API Backend bezpośrednio z otrzymanym JWT.

Zalecenia:

Światło/ciemny motyw automatycznie z 'themeParams'.
Nie przechowywać 'initData' w przeglądarce dłużej niż 10 minut; zaktualizować JWT z odświeżającym punktem końcowym (na sesję serwera).
Proces zamykania WebApp (na przykład, wyślij potwierdzenie działania do czatu).
Przestrzegaj ograniczeń WebView: tylko CSP, https, rozmiary, brak pop-upów.

Mini-przykład inicjalizacji:

js const tg = okno. Telegram. WebApp;
tg. gotowy ();
tg. rozszerzyć ();
const initData = tg. initData ;//send to your backend to exchange for JWT tg. MainButton. setText („Kontynuuj”). pokaż (). onClick (() => submit ());

8) Typowy przepływ

Profil/portfel (widok)

Użytkownik otwiera WebApp → weryfikacja 'initData' → wydaje JWT → pokazuje salda, CUS statusy/odpowiedzialne limity gry, historię transakcji (tylko do odczytu).

Turnieje/misje

W TWA pokazujemy tablice liderów i postępy misji (w czasie rzeczywistym, krótki sondaż/WS przez backend).

Przyciski: „Weź udział”, „Podziel się” (głębokie łącze dla znajomych), „Powiadom 5 minut przed rozpoczęciem”.

Ogłoszenia

Zdarzenia na platformie → event bus → konsument generuje tekst/klawiaturę inline → ' Message' z 'inline _ keyboard' (link „Open WebApp” lub deep-link).

Wsparcie opt-in/opt-out dla typów powiadomień (turnieje, wyjście, bonusy).

Wsparcie

Szybki bilet/FAQ w WebApp + „Otwórz czat z operatorem” przycisk.

Zweryfikować użytkownika (SSO), dokręcić kontekst ostatniej sesji/depozytu.

9) Aspekty płatności i zgodności

Transakcje pieniężne (wpłaty/wypłaty) - do szafy internetowej otwartej z przycisku bot (URL) lub z przycisku WebApp („Przejdź do szafki”).

Wewnątrz TWA, umożliwiają bezpieczne operacje tylko do odczytu i „łatwe” działania (wiązania, aktywacje promocyjne, turnieje).

Prywatność: nie rozmawiać PII; pokaż go tylko w WebApp (https, authorization).

Dzienniki zgody, zasady przechowywania, „prawo do usunięcia” - w profilu.

10) Przeciwpiechotne i ochronne

Sprawdź anomalie 'auth _ date' i timezony/ASN.

Limit szybkości przez 'telegram _ user _ id' i IP dla operacji wrażliwych (aktywacja promo, polecenie).

Ochrona głębokich linków: jednorazowe żetony, krótki TTL, wiązanie użytkownika/czatu.

W przypadku wysyłek zbiorczych - partia + jitter, sprawdź „cool” dla reklamacji/blokowania.

Weryfikacja plików/nośników z czatów (jeśli akceptujesz dokumenty): pobierz przez API BOT za pomocą 'file _ id', sprawdź typ/rozmiar/wirusy, przechowuj w pętli zgodności.

11) Obserwowalność, wpisy, limity

Metryka:

'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'.
Konwersja: otwarcie → autoryzacja → działanie docelowe (misja/turniej/powrót do biura).

Wpisy:

Błąd weryfikacji podpisu> X% w 5 minut
podczas wysyłania wiadomości 'FlلWait '/429.
Wzrost błędów 'deep _ link _ reuse' lub jednorazowych.

Dzienniki: JSON z 'trace _ id',' telegram _ user _ id' (pseudonim), bez PII; kojarzyć się z torami peronowymi.

12) Umowy API (szkice)

Wymiana 'initData' dla JWT

http
POST/v1/tg/exchange
{"init_data": "<string>"}
→ 200 {„jwt':” <krótkotrwały> „,” expires_in":900}

Profil

http
GET/v1/tg/me
Autoryzacja: Bearer <jwt>
→ 200 {"user_id":"u_123," "salda": [...], "kyc': {" poziom ":" podstawowy "}}

Subskrypcje powiadomień

http
POST/v1/tg/consents
{„promocje”: true, „turnieje”: true, „payouts”: true}

Dystrybucja (usługa wewnętrzna)

json
{
"szablon": "turniej _ start", "vars': {" nazwa ":" Halloween Sprint "," starts _ in ":" 5m "}," cele ": [{" chat _ id': 12345, "user _ id':" u _ 123 "}]
}

13) Przykłady UI w bot

Inline klawiatura „turniej”

json
{
"inline_keyboard": [
[{„tekst”: „Open Leadboard”, „web _ app”: {„url':” https ://twa. przykład/konkurs? id = październik "}}], [{" tekst ":" Zasady "," url': "https ://marka. com/contests/october/rules"}]
]
}

Odpowiedź-klawiatura „Menu główne”

Profil

Turnieje i misje
Premie i promocje
Obsługa klienta

14) Skala i tolerancja błędów

Webhook → kolejka → pracownicy (bezpaństwowcy); pozioma skala.

Zapisz „stan dialogowy” w Redis/DB (skończona maszyna stanu na 'chat _ id').

Mechanizm tworzenia kopii zapasowych „Aktualizacje” (długie sondaże) tylko w przypadku debugowania/folbacka.

Ograniczyć prędkość wysyłania ('wiadomości/sec') i rozmiar brunch mailingów; Planownik fal.

DR: token/tajna kopia zapasowa, wtórny punkt końcowy haka, skrypt „quick switch”.

15) Lista kontrolna dostawy

Webhook HTTPS, secret/mTLS, retry-security, idempotence 'update _ id'.
Weryfikacja podpisu „initData ”/Login Widget, okno świeżości, wymiana na krótki JWT.
Konto link/unlink, przechowywanie 'telegram _ user _ id'/' chat _ id', zgoda na powiadomienia.
Głębokie linki/„ startapp ”tylko jednorazowe, TTL i audyt.
WebApp: motyw, przyciski, plecy, odświeżyć JWT; CSP, https, brak PII w adresie URL.
Przeciwdziałanie oszustwom: ograniczenie stawki, sygnały ASN/proxy, ochrona przed skierowaniem.
Dystrybucje: kolejki, partia + jitter, monitorowanie FloodWait/429.
Obserwability: webhook/TWA/conversion metrics, alerts.
Dokumentacja UX/ograniczenia, polityka prywatności, DPA z Telegram jako kanał.
Runbook'i: kropla do haka, duplikat spike, masywne FlلWait, awaria TWA.

Wznów streszczenie

Integracja z Telegramem to nie „kolejny bot”, ale pełnoprawny kanał z bezpiecznym SSO (sprawdź 'initData '/Login), schludny WebApp UX i niezawodne przetwarzanie aktualizacji serwera. Utrzymuj transakcje pieniężne w głównej aplikacji, a w Telegram - silne scenariusze towarzyszące: profil, turnieje, misje, powiadomienia, wsparcie i skierowanie. Dodaj jednorazowe głębokie linki, krótkotrwałe JWT, kolejki i obserwowalność - i uzyskać szybki, bezpieczny i wymierny kanał wzrostu i zatrzymywania.