Telegram botlarynyň we WebApp-yň platforma bilen integrasiýasy

1) Näme üçin Telegram iGaming

Gurşaw we retenşn: çalt push-dialoglar (ýaryşlar/missiýalar, statuslar, mahabat habarnamalary).

Aňsat giriş: Telegram Login Widget/WebApp 'initData' parolsyz SSO.

Mini-müşderi: WebApp içerki tema/düwmeler we kontekstiň howpsuz geçirilmegi bilen Telegramyň içinde.

💡 Möhüm: "oýun mehanikasyny pula" botyň içine geçirmäň. Telegram-y hyzmatdaş kanal hökmünde ulanyň: habarnamalar, profil, KUS/statuslar, ýaryşlar/liderbordlar, mahabat, sapport, salgylanma flulary. Pul amallary - doly hukukly KYC/AML we PSP bilen web-kabinetde/programmada.

2) Integrasiýa arhitekturasy

Komponentler:

1. Telegram Bot (Bot API): täzelenmeleri gaýtadan işlemek (webhook), buýruklar/klawiatura, deep-links '/start payload '.

2. Telegram WebApp (TWA): Telegramyň içindäki Web-sahypa (in-app WebView), 'initData' alýar we Telegram UI bilen birleşdirilýär.

3. Auth/SSO platforma şlýuzy: 'initData '/Login Widget goluny barlamak, JWT gysga platformasyny çykarmak.

4. Backend API platformalary: profil/gapjyk/ýaryşlar/missiýalar/affiliates/sapport.

5. "Event bus": bellikler (Kafka/Redis Streams) → bot arkaly habar ibermek.

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

SSO akymy (gysgaça):

Telegram (WebApp/Login) → 'initData '/auth-payload → Auth şlýuzy HMAC barlaýar → JWT-ni berýär (5-15 minut) → WebApp/bot JWT-den API platformalaryny çagyrýar.

3) Ygtyýarlylandyrmagyň usullary

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

Telegramma WebApp-da 'initData' -ny ýerleşdirýär. Oňa HMAC-SHA256 serwerinde gol çekýärsiňiz.

Üstünlikli bolsaňyz, gysga JWT çykarýarsyňyz we (zerur bolsa) Telegram hasabyňyzy bar bolan profil bilen baglanyşdyrýarsyňyz.

'initData' -nyň pseudo barlagy:

python def verify_init_data(init_data: str, bot_token: str) -> dict:
init_data - setiri 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äzeligini barlaýarys (mysal üçin ≤ 10 min)
assert now() - int(data['auth_date'][0]) < 600 return data

B) Telegram Login Widget (daşarky sahypa)

Widget berýär 'id, first_name, auth_date, hash'. Barlag şuňa meňzeýär ('"Telegram Login" + bot_token').

WebApp ulanmasaňyz, adaty web kabinetine girseňiz amatly.

4) Hasaby baglanyşdyrmak we şahsyýet modeli

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

Baglanyşyk ýazgysyny döredýäris: 'platform _ user _ id username (nullable)' + razylyk atributlary (marketing/notifications).

Link/unlink strategiýalary:

Täze ulanyjy → ýönekeýleşdirilen profil döredýäris, ofisde telefon/e-poçta tassyklamagyňyzy haýyş edýäris.
Bar bolan → deep-link '/start link: 'ýa-da' start _ param 'bilen WebApp, baglanyşyk modalyny açýarys.
Unlink - sazlamalar arkaly, push bildirişlerine ability derrew yzyna alýarys.

5) Bot webhuk: howpsuzlyk we durnuklylyk

HTTPS + kesgitlenen domen, mTLS (mümkin boldugyça) we ygtybarly gizlin path ('/bot/< token> ') ýa-da sözbaşyda öz syry.

IP çäklendirmesi: Telegram IP whitelisting (eger infrastruktura rugsat berse), WAF düzgünleri.

Idempotentlik: 'update _ id' -ni saklaň, takyk bir gezek işläň.

Retrailer: Telegram 5 x/time-autda gaýtalaýar - bejergini saklaň <1 s, agyr - nobata duruň.

Rate-limits: habary ibermek üçin ýerli token-baketler (Telegram spamy çäklendirýär), köpçülikleýin ibermek üçin nobatlar.

Prosessor çarçuwasynyň mysaly:

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, başlangyç parametrleri we salgylanma

Görnüşiň baglanyşygy: 't. me/< bot>? start = '(base64url-da ~ 64 baýta çenli peýdaly maglumatlar).

Aşakdakylar üçin bir gezek ulanylýan nonce hökmünde ulanyň:

ugrukdyryş kampaniýalary ('aff _ id', 'campaign _ id', 'click _ id'), tamamlanmadyk flowyň dowamy (KYC step, missiýa, ýaryş), hasaby baglanyşdyrmak.
Laýyklygy saklaň 'nonce → intended_action → expires_at', bir-birini ediň.
WebApp üçin - 't. me//app? startapp = '(' initData-da alyň. start_param`).

7) Telegram WebApp: UX we integrasiýa

TWA:

Тема (`themeParams`), mainButton/secondaryButton, BackButton, `HapticFeedback`, `expand()`, `viewport`.
Ikitaraplaýyn alyş-çalyş: 'Telegram. WebApp. sendData () '→ botyň täzelenmesine uçar; ýa-da WebApp, alnan JWT bilen göni Backend API-ni çagyrýar.

Teklipler:

"themeParams" -dan awtomatiki usulda açyk/gara tema.
'initData' -ny brauzerde 10 minutdan köp saklamaň; JWT-ni refresh-endpoint bilen täzeläň (serwer sessiýasy boýunça).
WebApp-yň ýapylmagyny düzüň (mysal üçin, söhbetdeşlige tassyklamany iberiň).
WebView çäklendirmelerine hormat goýuň: CSP, diňe https, ölçegler, açylýan penjireler ýok.

Inisiatiwanyň kiçi mysaly:

js const tg = window. Telegram. WebApp;
tg. ready();
tg. expand();
const initData = tg. initData ;//JWT tg bilen alyş-çalyş etmek üçin backendiňize iberiň. MainButton. setText ('Dowam et'). show(). onClick(() => submit());

8) Adaty flowlar

Profil/gapjyk (görmek)

Ulanyjy WebApp açýar → 'initData' barlagy → JWT berýäris → balanslary, CCS statuslaryny/jogapkär oýnuň çäklerini, geleşikleriň taryhyny görkezýäris (read-only).

Ýaryşlar/missiýalar

TWA-da öňdebaryjy tagtalary we missiýalaryň ösüşini görkezýäris (hakyky wagt, arka tarapda gysga polling/WS).

Düwmeler: "Gatnaşmak", "Paýlaşmak" (dostlar üçin deep-link), "Başlamazdan 5 minut öň habar bermek".

Habarnamalar

Platforma wakalary → event bus → consumer teksti/inline klawiaturasyny emele getirýär → 'sendMessage' s 'inline _ keyboard' ("WebApp aç" baglanyşygy ýa-da deep-link).

Opt-in/opt-out habarnamalarynyň görnüşlerine (ýaryşlar, netijeler, bonuslar) goldaw beriň.

Sapport

Çalt bilet/WebApp-da SSS + "Operator bilen söhbetdeşligi aç" düwmesi.

Ulanyjyny (SSO) tassyklaň, soňky sessiýanyň/goýumyň mazmunyny çekiň.

9) Töleg we komplayens-taraplary

Pul amallary (goýumlar/netijeler) - botdan (URL düwmesi) ýa-da WebApp-dan ("Kabinete geçmek" düwmesi) açylan Web-kabinetine.

TWA-nyň içinde ygtybarly işlemäge we "ýeňil" hereketlere (baglanyşyklar, mahabat işjeňleşdirmeleri, ýaryşlar) rugsat beriň.

Gizlinlik: PII-ni söhbetdeşlige çykarmaň; diňe WebApp-da görkeziň (https, ygtyýarnama).

Razylyk ýazgylary, saklamak syýasaty, "aýyrmak hukugy" - profilde.

10) Antifrod we gorag

'auth _ date' we wagt zolagynyň/ASN anomaliýalarynyň täzeligini barlamak.

Rate-limit 'telegram _ user _ id' we IP duýgur amallar üçin (mahabaty işjeňleşdirmek, salgylanma).

Deep-links goragy: bir gezek ulanylýan bellikler, gysga TTL, ulanyjy/söhbetdeşlik baglanyşygy.

Köpçülikleýin poçtalar üçin - batch + jitter, şikaýatlara/blokirlemelere "sowatmak" barlagy.

Söhbetdeşliklerden faýllary/metbugaty barlamak (resminamalary kabul edýän bolsaňyz): Bot API-den 'file _ id' arkaly göçürip alyň, görnüşini/ululygyny/wiruslaryny barlaň, gabat gelýän konturda saklaň.

11) Syn ediliş, aladalar, çäkler

Metrikler:

`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`.
Öwrülişik: açyş → ygtyýarnama → maksatly hereket (missiýa/ýaryş/ofise gaýdyp gelmek).

Alertler:

Goly barlamak hatasy> X% 5 minutda.
Habar iberilende 'FloodWait '/429.
'deep _ link _ reuse' ýa-da bir gezek ulanylýan bellikleriň ýalňyşlyklary.

Logi: JSON c 'trace _ id', 'telegram _ user _ id' (lakamy), PII-siz; platforma söwdalary bilen habarlaşyň.

12) API şertnamalary (eskizler)

JWT 'initData' bilen alyş-çalyş

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

Habarnamalara abuna ýazylmalar

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

Poçta (içerki hyzmat)

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

13) Botdaky UI mysallary

Inline "ýaryş" klawiaturasy

json
{
"inline_keyboard": [
[{"text ":" Liderbord aç "", web _ app ": {" url":" https ://twa. example/contest? id = october"}}], [{"text ": "Düzgünler "", url":" https ://brand. com/contests/october/rules"}]
]
}

Reply klawiatura "Esasy menýu"

Profil

Ýaryşlar we missiýalar
Bonuslar we mahabat
Goldaw

14) Gerimi we şowsuzlyga çydamlylygy

Webhook → nobat → workers (stateless); gorizontal masştab.

"Dialogyň ýagdaýyny" Redis/DB (finite state machine per 'chat _ id') -de saklaň.

Ätiýaçlyk mehanizmi getUpdates (long polling) diňe debag/folbek üçin.

Iberiş tizligini ('messages/sec') we brunch poçta sanyny çäklendiriň; tolkun meýilleşdiriji.

DR: bellikleriň/syrlaryň yzy, ikinjisi webhook endpoint, "çalt geçiş" ssenarisi.

15) Azyk taýýarlygynyň çek-sanawy

Webhook HTTPS, syr/mTLS, retry-howpsuzlyk, idempotentlik 'update _ id'.
Goly barlamak 'initData '/Login Widget, täzelik penjiresi, gysga JWT üçin alyş-çalyş.
Link/unlink hasaby, saklamak 'telegram _ user _ id '/' chat _ id', habarnamalara razylyk.
Deep-links/' startapp 'diňe bir gezek ulanylýan, TTL we audit.
WebApp: tema, düwmeler, back, refresh JWT; CSP, https, URL-de PII-siz.
Antifrod: rate-limit, ASN/proxy signallary, salgylanma belliklerini goramak.
Poçta: nobatlar, batch + jitter, FloodWait/429 gözegçiligi.
Syn edilişi: webhook/TWA/öwrülişik metrikleri, töwekgelçilikler.
UX/çäklendirmeleri resminamalaşdyrmak, gizlinlik syýasaty, Telegram bilen DPA kanal hökmünde.
Runbook 'i: webhook ýykylmagy, dublikat köpelmegi, köpçülikleýin FloodWait, TWA şowsuzlygy.

Jemleme

Telegram bilen integrasiýa "başga bir bot" däl-de, ygtybarly SSO ('initData '/Login barlagy), seresaply UX WebApp we ygtybarly täzelenme serweri bilen doly hukukly kanal. Pul amallaryny esasy programmada saklaň, Telegramda bolsa güýçli hyzmatdaş ssenariýalary saklaň: profil, ýaryşlar, missiýalar, bellikler, sapport we salgylanma. Bir gezek ulanylýan deep-linkleri, gysga ömürli JWT-leri, nobatlary we syn edilişini goşuň we çalt, ygtybarly we ölçenen ösüş we saklaýyş kanalyny alyň.