Telegram botları və WebApp platforması ilə inteqrasiya

1) Nə üçün Telegram iGaming

Əhatə və retenshn: sürətli push dialoqlar (turnirlər/missiyalar, statuslar, promosyonlar haqqında bildirişlər).

Asan giriş: Şifrəsiz Telegram Login Widget/WebApp 'initData' vasitəsilə SSO.

Mini-müştəri: Yerli mövzu/düymələr və kontekstin təhlükəsiz ötürülməsi ilə Telegram daxilində WebApp.

💡 Vacibdir: «oyun mexanikasını» botun içərisinə köçürməyin. Telegram-dan müştəri kanalı kimi istifadə edin: bildirişlər, profil, KUS/statuslar, turnirlər/lider bordlar, promo, sapport, referans floları. Pul əməliyyatları - tam KYC/AML və PSP ilə veb-kabinet/tətbiqetmədə.

2) İnteqrasiya memarlığı

Komponentlər:

1. Telegram Bot (Bot API): yeniləmə emalı (webhook), komanda/klaviatura, deep-links '/start payload '.

2. Telegram WebApp (TWA): Telegram daxilində Web-səhifə (in-app WebView), 'initData' alır və Telegram UI ilə inteqrasiya edir.

3. Auth/SSO platforma şlüzü: 'initData '/Login Widget imzasının yoxlanılması, JWT qısamüddətli platformasının buraxılması.

4. Backend API platformaları: profil/cüzdan/turnirlər/missiyalar/affiliates/sapport.

5. Event bus: notifikasiyalar (Kafka/Redis Streams) → botla mesaj göndərmək.

6. Observability & Security: WAF, mTLS vebhuk, rate-limit, audit, alerting.

SSO axını (qısa):

Telegram (WebApp/Login) → 'initData '/auth-payload → Auth ağ yolu HMAC yoxlayır → JWT verir (5-15 dəqiqə) → WebApp/bot JWT ilə API platforma çağırır.

3) Avtorizasiya üsulları

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

Telegram WebApp 'initData' əvəz edir. Onu HMAC-SHA256 serverində = bot token açarı ilə imzalayırsınız.

Müvəffəqiyyətlə qısa JWT buraxırsınız və (lazım gələrsə) Telegram hesabınızı mövcud profil ilə əlaqələndirirsiniz.

'initData' saxta yoxlama kodu:

python def verify_init_data(init_data: str, bot_token: str) -> dict:
init_data - sətir 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 təravətini yoxlayın (məsələn, 10 dəq ≤)
assert now() - int(data['auth_date'][0]) < 600 return data

B) Telegram Login Widget (xarici səhifə)

Widget verir 'id, first_name, auth_date, hash'. Yoxlama oxşardır ('Telegram Login "+ bot_token').

WebApp istifadə etmirsinizsə və adi veb kabinetinizə daxil olursanız uyğundur.

4) Hesabın bağlanması və şəxsiyyət modeli

Əsas açar: 'telegram _ user _ id' ('from. id`).

«platform _ user _ id username (nullable)» + razılıq atributları (marketing/notifications).

link/unlink strategiyaları:

Yeni istifadəçi → sadələşdirilmiş profil yaradın, xahiş edirik ofis telefon/e-mail təsdiq.
Mövcud → deep-link '/start link: 'və ya' start _ param 'ilə WebApp, bağlamaq üçün bir modal açın.
Unlink - parametrlər vasitəsilə, dərhal push bildirişlərinə ability geri çağırın.

5) Vebhuk bot: təhlükəsizlik və sabitlik

HTTPS + sabit domen, mTLS (mümkünsə) və etibarlı gizli yol ('/bot/< token> ') və ya başlıqda öz sirri.

IP məhdudiyyəti: whitelisting Telegram IP (infrastruktur imkan verərsə), WAF qaydaları.

İdempotentlik: 'update _ id' saxlayın, tam olaraq bir dəfə işləyin.

Retrailer: Telegram 5xx/time-autda təkrar edir - emal edin <1 s, ağır - növbəyə.

Rate-limits: mesajların göndərilməsi üçün lokal token-baketlər (Telegram spam məhdudlaşdırır), kütləvi poçt xətləri üçün növbələr.

Prosessor çərçivəsinin nümunəsi:

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, start-parametrləri və istinad

Növ bağlantısı: 't. me/< bot>? start = '(base64url-da ~ 64 bayta qədər faydalı məlumat).

üçün birdəfəlik nonce kimi payload istifadə edin:

referans kampaniyaları ('aff _ id', 'campaign _ id', 'click _ id'), yarımçıq flounun davamı (KYC step, missiya, turnir), hesabın bağlanması.
'nonce → intended_action → expires_at' uyğunluğunu saxlayın, tək istifadə edin.
WebApp üçün - 't. me//app? startapp = '(daxil olun' initData. start_param`).

7) Telegram WebApp: UX və inteqrasiya

TWA fırçaları:

Тема (`themeParams`), mainButton/secondaryButton, BackButton, `HapticFeedback`, `expand()`, `viewport`.
İkitərəfli mübadilə: 'Telegram. WebApp. sendData () '→ botun yenilənməsinə gələcək; ya WebApp alınan JWT ilə birbaşa Backend API çağırır.

Tövsiyələr:

Açıq/qaranlıq mövzu avtomatik olaraq 'themeParams' -dan.
Brauzerdə 'initData' -nı 10 dəqiqədən çox saxlamayın; JWT refresh-end nöqtəsi ilə yeniləyin (server sessiyası üzrə).
WebApp-ın bağlanmasını emal edin (məsələn, chata təsdiq göndərin).
WebView məhdudiyyətlərinə hörmət edin: CSP, yalnız https, ölçülər, açılır pəncərələr olmadan.

Mini başlanğıc nümunəsi:

js const tg = window. Telegram. WebApp;
tg. ready();
tg. expand();
const initData = tg. initData ;//JWT tg mübadiləsi üçün backend-ə göndərin. MainButton. setText ('Davam'). show(). onClick(() => submit());

8) Tipik Flow

Profil/cüzdan (bax)

İstifadəçi WebApp açır → doğrulama 'initData' → JWT veririk → balansları, CCC statuslarını/məsuliyyətli oyunun limitlərini, əməliyyatların tarixçəsini (read-only) göstərir.

Turnirlər/missiyalar

TWA-da lider bordları və missiyaların irəliləyişini göstəririk (real-time, qısa polling/WS backend vasitəsilə).

Düymələr: «Iştirak et», «Paylaş» (dostlar üçün deep-link), «Başlamazdan 5 dəqiqə əvvəl bildirin».

Bildirişlər

Platforma hadisələri → event bus → consumer mətn/inline klaviatura formalaşdırır → 'sendMessage' s 'inline _ keyboard' («WebApp aç» bağlantısı və ya deep-link).

Opt-in/opt-out-da bildiriş növlərini (turnirlər, çıxışlar, bonuslar) dəstəkləyin.

Sapport

Tez bilet/WebApp SSS + «Operator ilə chat aç» düyməsi.

İstifadəçini (SSO) yoxlayın, son sessiya/depozit kontekstini çəkin.

9) Ödəniş və komplayens aspektləri

Pul əməliyyatları (depozitlər/çıxışlar) - botdan (URL düyməsi) və ya WebApp-dan («Kabinetə keçid» düyməsi) açılan veb kabinetə.

TWA daxilində təhlükəsiz read-only əməliyyatlara və «yüngül» hərəkətlərə (bağlamalar, promo aktivləşdirmələr, turnirlər) icazə verin.

Gizlilik: PII-ni söhbətə gətirməyin; yalnız WebApp daxilində göstərin (https, authorization).

Razılıq qeydləri, saxlama siyasəti, «silinmə hüququ» - profildə.

10) Antifrod və müdafiə

'auth _ date' və taymzon/ASN anomaliyalarının təzəliyi yoxlanılır.

Rate-limit ilə 'telegram _ user _ id' və IP həssas əməliyyatlar (promo aktivləşdirilməsi, referal).

Deep-links qorunması: birdəfəlik tokenlər, qısa TTL, istifadəçi/chat.

Kütləvi poçt üçün - batch + jitter, şikayət/bloklama «soyutma» yoxlama.

Chatlardan faylların/medianın yoxlanılması (əgər sənədləri qəbul edirsinizsə): 'file _ id' ilə Bot API-dən yükləyin, növü/ölçüsü/virusları yoxlayın, uyğunluq konturunda saxlayın.

11) Müşahidə, risklər, limitlər

Metriklər:

`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`.
Dönüşüm: açma → avtorizasiya → məqsədli fəaliyyət (missiya/turnir/kabinetə qayıdış).

Alertlər:

İmzanı yoxlamaq üçün səhv> X% 5 dəq.
'FloodWait '/429 mesaj göndərərkən.
'deep _ link _ reuse' və ya birdəfəlik tokenlərin səhvlərinin artması.

Loqlar: JSON ilə 'trace _ id', 'telegram _ user _ id' (təxəllüs), PII olmadan; platforma treysləri ilə əlaqə saxlayın.

12) API müqavilələri (eskizlər)

JWT üçün 'initData' mübadiləsi

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

Profil

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

Bildirişlərə abunə

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

Poçt (daxili xidmət)

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

13) Botda UI nümunələri

Inline-klaviatura «turnir»

json
{
"inline_keyboard": [
[{«text»: «», web _ app «: {» url «:» https ://twa. example/contest? id = october»}}], [{«text «: «Qaydalar ««, url»:» https ://brand. com/contests/october/rules"}]
]
}

Reply-klaviatura «Əsas menyu»

Profil

Turnirlər və missiyalar
Bonuslar və Promosyonlar
Dəstək

14) Miqyaslı və uğursuzluğa davamlılıq

Webhook → növbə → işçilər (stateless); üfüqi miqyas.

«Dialoq vəziyyətini» Redis/DB-də saxlayın (finite state machine per 'chat _ id').

Ehtiyat mexanizmi getUpdates (long polling) yalnız debag/folback üçün.

Göndərmə sürətini ('messages/sec') və brunch poçtlarının ölçüsünü məhdudlaşdırın; dalğa planlaşdırıcı.

DR: ikincil webhook endpoint, «sürətli keçid» ssenarisi.

15) Hazırlıq yoxlama siyahısı

Webhook HTTPS, gizli/mTLS, retry-təhlükəsizlik, idempotentlik 'update _ id'.
'initData '/Login Widget imza yoxlama, təzəlik pəncərə, qısa JWT mübadiləsi.
Link/unlink hesabı, saxlama 'telegram _ user _ id '/' chat _ id', bildirişlərə razılıq.
Deep-links/' startapp 'yalnız birdəfəlik, TTL və audit.
WebApp: mövzu, düymələr, back, refresh JWT; CSP, https, URL-də PII olmadan.
Antifrod: rate-limit, ASN/proxy siqnalları, referalların qorunması.
Poçt: növbələr, batch + jitter, FloodWait/429 monitorinqi.
Müşahidə: webhook/TWA/dönüşüm metrikləri, risklər.
UX/məhdudiyyətlərin sənədləşdirilməsi, gizlilik siyasəti, kanal kimi Telegram ilə DPA.
Runbook 'i: webhook düşməsi, təkrarlanan sıçrama, kütləvi FloodWait, TWA imtina.

Xülasə

Telegram ilə inteqrasiya «başqa bir bot» deyil, təhlükəsiz SSO (yoxlama 'initData '/Login), səliqəli UX WebApp və etibarlı yeniləmə serveri ilə tam hüquqlu bir kanaldır. Pul əməliyyatlarını əsas tətbiqdə saxlayın, Telegram-da isə güclü yoldaş ssenariləri: profil, turnirlər, missiyalar, notifikasiyalar, sapport və referalka. Birdəfəlik deep links, qısa ömürlü JWT, növbə və müşahidə əlavə edin - və sürətli, təhlükəsiz və ölçülebilir böyümə və saxlama kanalı əldə edin.