Integrarea roboților telegramă și WebApp cu platforma

1) De ce telegrama în iGaming

Reach și retenție: dialoguri rapide (notificări de turneu/misiune, statusuri, promo-uri).

Conectare ușoară: SSO prin Telegram Login Widget/WebApp „initData” fără parolă.

Mini-client: WebApp în interiorul telegramei cu temă nativă/butoane și transfer de context sigur.

💡 Important: nu transferați „mecanica jocului pentru bani” în interiorul botului. Utilizați Telegram ca un canal companion: notificări, profil, CUS/statusuri, turnee/clasamente, promo, suport, fluxul de trimitere. Tranzacții bănești - într-un cabinet web/aplicație cu un KYC/AML complet și PSP.

2) Arhitectura de integrare

Componente:

1. Telegram Bot (Bot API): actualizări de procesare (webhook), comenzi/tastaturi, adâncime link-uri '/start sarcină utilă '.

2. Telegram WebApp (TWA): Pagina Web din interiorul Telegram (in-app WebView), primește 'initData' și se integrează cu Telegram UI.

3. Auth/SSO platforma gateway: verificarea semnăturii 'initData '/Login Widget, lansarea platformei de scurtă durată JWT.

4. Platforme API backend: profil/portofel/turnee/misiuni/afiliate/suport.

5. Event bus: notificări (Kafka/Redis Streams) → trimiterea mesajelor prin bot.

6. Observație și securitate: WAF, mTLS la webhook, rate-limit, audit, alertă.

Flux SSO (scurt):

Telegrama (WebApp/Login) → „initData ”/auth-sarcină utilă → Auth gateway verifică problemele de → HMAC JWT (5-15 minute) → WebApp/bot apeluri platforma API cu JWT.

3) Metode de autorizare

A) Telegrama WebApp ('fereastră. Telegramă. WebApp ')

Telegrama înlocuiește „initData” în WebApp. Îl semnați pe serverul HMAC-SHA256 cu tasta = bot token.

Dacă reușiți, eliberați un JWT scurt și (dacă este necesar) conectați contul Telegram la un profil existent.

Cod pseudo de validare „initData”:

python def verify_init_data (init_data: str, bot_token: str) -> dict:
init_data - query-like string „key1 =.. & key2 =”..
date = parse_qs (init_data)
hash_provided = date. pop ('hash') [0]
check_string = '\n' .join ([f „{k} = {v [0]}” pentru k în sortate (date. chei ())])
secret = hmac. nou (b „WebAppData”, bot_token. codifică (), „sha256”). digest ()
calc = hmac. nou (secret, check_string. codifică (), „sha256”). hexdigest ()
afirma hmac. compare_digest (calc, hash_provided)
verificați prospețimea auth_date (de exemplu, ≤ 10 minute)
afirmă acum () - int (date ['auth _ date'] [0]) <600 date de retur

B) Telegrama Conectare Widget (pagina externă)

Widget-ul dă 'id, first_name, auth_date, hash'. Verificarea este similară („Telegram Login” + bot_token').

Potrivit dacă nu utilizați WebApp, dar introduceți un dulap web obișnuit.

4) Conectarea contului și modelul de identitate

Cheie principală: 'telegram _ user _ id' (' from. id').

Creăm înregistrarea legării: 'platform _ user _ id username (nullable)' + atributele consimțământului (marketing/notificări).

Strategii de link/unlink:

Un nou utilizator → crea un profil simplificat, vă rugăm să confirmați telefonul/e-mail în birou.
Link-ul existent deep-link → '/start: 'sau WebApp cu' start _ param ', deschideți modalul pentru legare.
Unlink - prin setările, vom revoca instantaneu capacitatea de a împinge notificări.

5) Webhook Bot: Siguranță și durabilitate

HTTPS + domeniu fix, mTLS (dacă este posibil) și cale secretă validă ('/bot/< token> ') sau propriul secret din antet.

Restricție IP: whitelisting Telegram IP (dacă infrastructura permite), reguli WAF.

Idempotence: păstrați 'update _ id', procesați exact o dată.

Retrai: Telegrama se repetă la 5xx/timeout - păstrați procesarea <1 s, grele - în linie.

Rate-limite: locale token-găleți pentru trimiterea de mesaje (Telegram limite de spam), cozi pentru corespondență în masă.

Exemplu cadru handler:

piton
@ app. post („/telegram/webhook ”)
def on_update (u: Actualizare):
dacă este văzut (u. update_id): retur „ok”
coadă. publicare ("tg. actualizări," u. json ()) # async consuma mark_seen (u. update_id)
întoarce „ok”

6) Legături profunde, parametrii de pornire și sesizare

Vezi referinta: 't. me/< bot>? start = '(până la ~ 64 octeți de sarcină utilă în base64url).

Utilizați sarcina utilă ca one-time nonce pentru:

campanii de sesizare ('aff _ id',' campaign _ id', 'click _ id'), continuarea fluxului neterminat (KYC step, misiune, turneu), conectarea contului.
Păstrați conformitate "nonce , face de unică folosință.
Pentru WebApp - 't. me/< bot >/app? startapp = '(get in' initData. start_param').

7) Telegrama WebApp: UX și integrare

Caracteristică TWA:

Тема ('themeParams'), mainButton/secundarButton, BackButton,' HapticFeedback ',' extinde () ',' viewport '.
Schimb bilateral: 'Telegramă. WebApp. sendData () "→ va ajunge în actualizarea bot; sau WebApp apelează API-ul Backend direct cu JWT primit.

Recomandări:

Temă ușoară/întunecată automat din 'themeParams'.
Nu stocați „initData” în browser mai mult de 10 minute; actualizați JWT cu un punct final de reîmprospătare (pe sesiune de server).
Procesul de închidere WebApp (de exemplu, trimite confirmarea acțiunii la chat).
Respectați restricțiile WebView: CSP, numai https, dimensiuni, fără pop-up-uri.

Inițializare mini-exemplu:

js const tg = fereastră. Telegramă. WebApp;
tg. gata ();
tg. extinde ();
const initData = tg. initData ;//trimite la backend pentru a schimba JWT tg. MainButton. SetText ('Continuă'). spectacol (). onClick (() => trimite ());

8) Flux tipic

Profil/Portofel (Vizualizare)

Utilizatorul deschide WebApp → verificarea „initData” → emite un → JWT care prezintă echilibre, statusuri CUS/limite de joc responsabile, istoricul tranzacțiilor (read-only).

Turnee/Misiuni

În TWA, prezentăm clasamente și progresul misiunii (timp real, sondaj scurt/WS prin backend).

Butoane: „Participă”, „Share” (adâncime-link pentru prieteni), „Notifică 5 minute înainte de start”.

Notificări

Evenimente platformă → eveniment bus → consumator generează text/inline tastatură → 'sendMessage' cu 'inline _ keyboard' (link „Open WebApp” sau deep-link).

Suport opt-in/opt-out pentru tipurile de notificare (turnee, ieșire, bonusuri).

Suport

Bilet rapid/Întrebări frecvente în WebApp + „Deschideți chat-ul cu operatorul” buton.

Verificați utilizatorul (SSO), strângeți contextul ultimei sesiuni/depozit.

9) Aspecte de plată și conformitate

Tranzactii monetare (depuneri/retrageri) - catre un cabinet web deschis de la un bot (buton URL) sau de la WebApp (butonul „Go to cabinet”).

În cadrul TWA, permiteți operațiuni sigure de citire și acțiuni „ușoare” (legături, activări promoționale, turnee).

Confidențialitate: nu chat-ul PII; Arată-l numai în interiorul WebApp (https, autorizare).

Jurnalele de consimțământ, politica de păstrare, „dreptul de a șterge” - în profil.

10) Antifraudă și protecție

Verificați anomaliile de 'auth _ date' și fusul orar/ASN.

Rate-limit prin 'telegram _ user _ id' și IP pentru operațiuni sensibile (activarea promo, sesizare).

Protecție deep-link-uri: token-uri o singură dată, TTL scurt, user/chat obligatoriu.

Pentru corespondență în masă - lot + jitter, verificați „cool” pentru reclamații/blocare.

Verificarea fișierelor/mediilor din chat (dacă acceptați documente): descărcați prin Bot API prin 'file _ id', verificați tipul/dimensiunea/virușii, stocați într-o buclă de conformitate.

11) Observabilitate, alerte, limite

Măsurători:

'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'.
Conversie: deschiderea autorizației → → acțiune țintă (misiune/turneu/întoarcere la birou).

Alerte:

Eroare de verificare a semnăturii> X% în 5 minute
'FloodWait '/429 la trimiterea mesajelor.
Creșterea erorilor de token 'deep _ link _ reutilizare' sau o singură dată.

Jurnale: JSON cu 'trace _ id',' telegram _ user _ id' (pseudonim), fără PII; asociat cu piste de platformă.

12) contracte API (schițe)

Schimbul de „date init” pentru JWT

http
POST/v1/tg/schimb
{"init_data": "<string>"}
→ 200 {„jwt':” <short-life> „,” expires_in":900}

Profilul

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

Abonamente de notificare

http
POST/v1/tg/consimțăminte
{„promoții”: adevărat, „turnee”: adevărat, „plăți”: adevărat}

Distribuție (serviciu intern)

json
{
„template”: „tournament _ start”, „vars': {” name „:” Halloween Sprint „,” starts _ in „:” 5m „},” targets': [{„chat _ id': 12345,” user _ id': „u _ 123”}]
}

13) Exemple de UI în bot

Inline tastatură „turneu”

json
{
"inline_keyboard": [
[{"text": "Open Leadboard'," web _ app ": {" url': "https ://twa. exemplu/concurs? id = october "}], [{" text ":" Reguli "," url': "https ://brand. com/concursuri/octombrie/reguli"}]
]
}

Răspuns-tastatură „Meniu principal”

Profilul

Turnee și misiuni
Bonusuri și promoții
Asistență pentru clienți

14) Scară și toleranță la erori

Webhook → coadă → lucrători (apatrizi); scară orizontală.

Stocați „starea de dialog” în Redis/DB (mașină de stare finită pe 'chat _ id').

Mecanism de backup getUpdates (sondaj lung) numai pentru depanare/folback.

Limitați viteza de trimitere („mesaje/sec”) și dimensiunea mesajelor de brunch; planificator de valuri.

DR: token/copie de rezervă secretă, punctul final secundar de căutare web, scriptul „comutator rapid”.

15) Lista de verificare a livrării

Webhook HTTPS, secret/mTLS, retry-security, idempotency 'update _ id'.
Verificarea semnăturii 'initData '/Login Widget, fereastră de prospețime, schimb pentru un JWT scurt.
Link/deblocare cont, stocarea 'telegram _ user _ id'/' chat _ id', consimțământul pentru notificări.
Legături profunde/' startapp 'numai de unică folosință, TTL și audit.
WebApp: temă, butoane, spate, reîmprospăta JWT; CSP, https, fără PII în URL.
Antifraudă: limită de rată, semnale ASN/proxy, protecție împotriva trimiterilor.
Distribuții: cozi, lot + jitter, monitorizare FloodWait/429.
Observabilitate: webhook/TWA/valori de conversie, alerte.
Documentație UX/restricție, politica de confidențialitate, DPA cu Telegram ca un canal.
Runbook 'și: cădere webhook, spike duplicat, FloodWait masiv, eșec TWA.

Rezumat reluare

Integrarea cu Telegram nu este „un alt bot”, ci un canal cu drepturi depline cu SSO securizat (check 'initData '/Login), UX WebApp și procesarea serverului fiabil de actualizări. Păstrați tranzacțiile bănești în aplicația principală și în Telegram - scenarii puternice de însoțire: profil, turnee, misiuni, notificări, suport și trimitere. Adăugați legături adânci, JWT-uri de scurtă durată, cozi și observabilitate - și obțineți un canal de creștere și retenție rapid, sigur și măsurabil.