Telegram-botlar va WebAppni platforma bilan integratsiyalash

1) Nima uchun Telegram iGaming

Qamrov va retenshn: tezkor push-dialoglar (turnirlar/missiyalar, maqomlar, promolar to’g "risidagi xabarnomalar).

Oson kirish: Telegram Login Widget/WebApp’initData’orqali SSO parolsiz.

Mini-mijoz: mahalliy mavzu/tugmalar va kontekstni xavfsiz uzatish bilan Telegram ichidagi WebApp.

💡 Muhimi: «o’yin mexanikasini pulga» botning ichiga o’tkazmang. Telegram’dan sherik-kanal sifatida foydalaning: bildirishnomalar, profil, KTS/maqomlar, turnirlar/yetakchi taxtalar, promo, sapport, referial floular. Pul operatsiyalari - to’liq KYC/AML va PSP bo’lgan veb-kabinet/ilovada.

2) Integratsiya arxitekturasi

Komponentlar:

1. Telegram Bot (Bot API): yangilanishlarni qayta ishlash (webhook), buyruq/klaviatura, deep-links ’/start payload’.

2. Telegram WebApp (TWA): Telegram ichidagi Web-sahifa (in-app WebView),’initData’ni oladi va Telegram UI bilan integratsiyalashadi.

3. Platformaning Auth/SSO shlyuzi:’initData ’/Login Widget imzosini tekshirish, JWT qisqa platformasini chiqarish.

4. Backend API platformalari: profil/hamyon/turnirlar/missiyalar/affiliates/sapport.

5. Event bus: notifikatsiyalar (Kafka/Redis Streams) → bot orqali xabar yuborish.

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

SSO oqimi (qisqacha):

Telegram (WebApp/Login) →’initData ’/auth-payload → Auth shlyuzi HMACni tekshiradi → JWT (5-15 daqiqa) beradi → WebApp/bot JWT bilan API platformalarini chaqiradi.

3) Avtorizatsiya usullari

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

Telegram’initData’ni WebApp’ga joylashtiradi. Uni HMAC-SHA256 serverida = bot token bilan imzolaysiz.

Agar muvaffaqiyatli boʻlsangiz, qisqa JWTni chiqarasiz va (agar kerak boʻlsa) Telegram akkauntini mavjud profil bilan bogʻlaysiz.

Tekshirish soxta hujjati’initData’:

python def verify_init_data(init_data: str, bot_token: str) -> dict:
init_data - query-like satri «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 yangiligini tekshiramiz (masalan, 10 daqiqa ≤)
assert now() - int(data['auth_date'][0]) < 600 return data

B) Telegram Login Widget (tashqi sahifa)

Widget’id, first_name, auth_date, hash’beradi. Tekshirish xuddi shunday (’Telegram Login’+ bot_token').

Agar siz WebApp’dan foydalanmasangiz, balki oddiy veb-kabinetga kirsangiz mos keladi.

4) Akkauntni bog’lash va identifikatsiya modeli

Birlamchi kalit:’telegram _ user _ id’(’from. id`).

Ulanish yozuvini yaratmoqdamiz:’platform _ user _ id username (nullable)’+ rozilik atributlari (marketing/notifications).

Link/unlink strategiyalari:

Yangi foydalanuvchi → soddalashtirilgan profilni yaratmoqdamiz, sizdan telefon/elektron pochtani tasdiqlashingizni so’raymiz.
Mavjud → deep-link ’/start link: ’yoki WebApp’start _ param’bilan bog’lash uchun modal ochilmoqda.
Unlink - sozlash orqali, push bildirishnomalariga abilitni darhol qaytarib olamiz.

5) Vebxuk bot: xavfsizlik va barqarorlik

HTTPS + oʻrnatilgan domen, mTLS (iloji boricha) va valid secret path (’/bot/< token>’) yoki sarlavhadagi shaxsiy sir.

Cheklangan IP: whitelisting Telegram IP (agar infratuzilma imkon bersa), WAF qoidalari.

Idempotentlik:’update _ id’ni saqlang.

Retrai: Telegram 5xx/taym-autda takrorlaydi - qayta ishlashni <1 s ushlab turing, og’ir - navbatda turing.

Rate-limits: xabar yuborish uchun lokal token-baketlar (Telegram spamni cheklaydi), ommaviy tarqatish uchun navbatlar.

Ishlov beruvchining karkas namunasi:

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-parametrlar va referalka

Turning bogʻlamasi:’t. me/< bot>? start = ’(base64url ~ 64 baytgacha).

Payload’dan bir martalik nonce sifatida foydalaning:

referial kampaniyalar (’aff _ id’,’campaign _ id’,’click _ id’), tugallanmagan floularni davom ettirish (KYC step, missiya, turnir), akkauntni bog’lash.
Muvofiqlikni saqlang’nonce → intended_action → expires_at', single-use.
WebApp uchun -’t. me//app? startapp = ’(’initData’da oling. start_param`).

7) Telegram WebApp: UX va integratsiya

TWA fichlari:

Тема (`themeParams`), mainButton/secondaryButton, BackButton, `HapticFeedback`, `expand()`, `viewport`.
Ikki tomonlama almashinuv:’Telegram. WebApp. sendData ()’→ bot apdeytiga keladi; yoki WebApp sizning Backend API-ni olingan JWT bilan toʻgʻridan-toʻgʻri chaqiradi.

Tavsiyalar:

Yorqin/qorong’u mavzu avtomatik ravishda’themeParams’dan.
’initData’ ni brauzerda 10 daqiqadan ortiq saqlamang; JWTni refresh-endpoint bilan yangilang (server sessiyasi boʻyicha).
WebApp yopilishini koʻrib chiqing (masalan, chat orqali tasdiqlashni yuboring).
WebView: CSP cheklovlarini hurmat qiling, faqat https, o’lchamlari, ko’tariladigan oynalarsiz.

Ishga tushirishning mini-namunasi:

js const tg = window. Telegram. WebApp;
tg. ready();
tg. expand();
const initData = tg. initData ;//JWT tg bilan almashish uchun backendga yuboring. MainButton. setText (’Davom etish’). show(). onClick(() => submit());

8) Namunaviy flou

Profil/hamyon (koʻrish)

Foydalanuvchi WebApp ochadi → verifikatsiya’initData’→ JWT bering → balans, KSning holati/mas’ul o’yin limitlari, tranzaksiyalar tarixini ko’rsating (read-only).

Turnirlar/missiyalar

TWAda biz yetakchi bordlar va missiyalarning rivojlanishini ko’rsatamiz (real taym, qisqa polling/WS).

Tugmalar: «Ishtirok etish», «Boʻlishish» (doʻstlar uchun deep-link), «Boshlashdan 5 daqiqa oldin xabardor qilish».

Xabarnomalar

Platforma voqealari → event bus → consumer matn/inline klaviatura shakllantiradi →’sendMessage’s’inline _ keyboard’(«WebApp ochish» yoki deep-link).

Opt-in/opt-out xabarnoma turlarini (turnirlar, chiqish, bonuslar) qoʻllab-quvvatlang.

Sapport

Tez chipta/WebApp’da SSS + «Operator bilan chat ochish» tugmasi.

Foydalanuvchini (SSO) tekshiring, oxirgi sessiya/depozit kontekstini torting.

9) To’lov va komplayens jihatlari

Pul tranzaksiyalari (depozitlar/xulosalar) - botdan (URL tugmasi) yoki WebApp-dan («Kabinetga o’tish» tugmasi) ochilgan veb-kabinetga.

TWA ichida xavfsiz ishlashga ruxsat bering read-only va «engil» harakatlar (bogʻlash, reklama faollashtirish, turnirlar).

Maxfiylik: PIIni chatga kiritmang; uni faqat WebApp (https, avtorizatsiya) ichida koʻrsating.

Rozilik daftarlari, saqlash siyosati, «olib tashlash huquqi» - profilda.

10) Antifrod va himoya

’auth _ date’ va taymzon/ASN anomaliyalarining yangiligini tekshirish.

«telegram _ user _ id» bo’yicha rate-limit va sezgir operatsiyalarga IP (promo aktivatsiyasi, referal).

Deep-links himoyasi: bir martalik tokenlar, qisqa TTL, foydalanuvchi/chatga ulanish.

Ommaviy tarqatish uchun - batch + jitter, shikoyatlarni/blokirovkalarni tekshirish.

Chat fayllari/media verifikatsiyasi (agar hujjatlarni qabul qilayotgan boʻlsangiz): Bot API orqali’file _ id’orqali yuklab oling, turini/oʻlchamini/viruslarini tekshiring, komplayens-konturda saqlang.

11) Kuzatish darajasi, alertlar, limitlar

Metriklar:

`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`.
Konvertatsiya: ochish → avtorizatsiya → maqsadli harakat (missiya/turnir/kabinetga qaytish).

Alertlar:

Imzoni tekshirishda xato roʻy berdi> X% 5 daqiqada.
Xabarlarni joʻnatishda’FloodWait ’/429.
’deep _ link _ reuse’ yoki bir martalik tokenlarning xatolari.

Logi: JSON s’trace _ id’,’telegram _ user _ id’(taxallusi), PIIsiz; platforma treyslari bilan bog’laning.

12) API kontraktlari (eskizlar)

JWT’initData’bilan almashish

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"} }

Xabarnomaga obuna

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

Tarqatish (ichki xizmat)

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

13) Botdagi UI misollari

«Turnir» inline klaviaturasi

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

Reply-klaviatura «Asosiy menyu»

Profil

Turnirlar va missiyalar
Bonuslar va promo
Qoʻllab-quvvatlash

14) Ko’lami va ishdan chiqishga chidamliligi

Webhook → navbat → vorkerlar (stateless); gorizontal masshtab.

«Dialog holati» ni Redis/DB (finite state machine per’chat _ id’) da saqlang.

getUpdates (long polling) faqat debag/folbek uchun zaxira mexanizmi.

Joʻnatish tezligini (’messages/sec’) va brunch joʻnatish hajmini cheklang; to’lqinlarni rejalashtiruvchi.

DR: token/sirlarni qaytarish, ikkilamchi webhook endpoint, tezkor almashtirish skripti.

15) Oziq-ovqat tayyorgarligi chek-varaqasi

Webhook HTTPS, maxfiy/mTLS, retry-xavfsizlik, idempotentlik’update _ id’.
’initData ’/Login Widget’imzosini tekshirish, yangilik oynasi, qisqa JWT almashtirish.
Link/unlink akkaunt, saqlash’telegram _ user _ id ’/’ chat _ id’, rozilik bildirishnomalar.
Deep-links/’ startapp’faqat bir martalik, TTL va audit.
WebApp: mavzu, tugmalar, back, refresh JWT; CSP, https, URLda PIIsiz.
Antifrod: rate-limit, ASN/proksi-signallar, referalkalarni himoya qilish.
Tarqatish: navbatlar, batch + jitter, FloodWait/429 monitoringi.
Kuzatish darajasi: webhook/TWA/konversiya metrikasi, alertlar.
UX/cheklovlar hujjatlari, maxfiylik siyosati, Telegram kanali bilan DPA.
Runbook’i: webhook qulashi, dublikatlar ko’payishi, FloodWait ommaviy, TWA rad etilishi.

Xulosa

Telegram bilan integratsiya qilish «boshqa bot» emas, balki xavfsiz SSO (tekshirish’initData ’/Login), ehtiyotkorlik bilan UX WebApp va ishonchli yangilanishlarni qayta ishlash bilan to’liq kanaldir. Pul operatsiyalarini asosiy ilovada, Telegram’da esa kuchli sherik-stsenariylarda: profil, turnirlar, missiyalar, notifikatsiyalar, sapport va referalkada saqlang. Bir martalik deep-links, qisqa umr ko’radigan JWT, navbatlar va kuzatuv darajasini qo’shing va tezkor, xavfsiz va o’lchovli o’sish va ushlab turish kanaliga ega bo’ling.