Telegram ბოტების და WebApp- ის ინტეგრაცია პლატფორმასთან

1) რატომ არის Telegram iGaming

გაშუქება და ჭრა: სწრაფი დიალოგები (შეტყობინებები ტურნირების/მისიების, სტატუსის, პრომო).

მსუბუქი შეყვანა: SSO Telegram Login Widget/WebApp 'initData' - ის პაროლის გარეშე.

მინი კლიენტი: WebApp Telegram- ის შიგნით მშობლიური თემით/ღილაკებით და კონტექსტის უსაფრთხო გადაცემით.

💡 მნიშვნელოვანია: არ გადაიტანოთ „თამაშის მექანიკა ფულზე“ შიგნით. გამოიყენეთ Telegram, როგორც თანამგზავრული არხი: შეტყობინებები, პროფილი, KUS/სტატუსები, ტურნირები/ლიდერები, პრომო, საფოსტო პორტი, რეფერერული ფლეშ. ფულადი ოპერაციები - ვებ - ოფისში/განაცხადში სრული KYC/AML და PSP.

2) ინტეგრაციის არქიტექტურა

კომპონენტები:

1. Telegram Bot (Bot API): განახლება (webhook), ბრძანება/კლავიატურა, deep-links '/start payload '.

2. Telegram WebApp (TWA): Web გვერდი Telegram- ის შიგნით (App WebView), იღებს 'initData "და ინტეგრირდება UI Telegram- სთან.

3. Auth/SSO კარიბჭე პლატფორმა: ხელმოწერის გადამოწმება 'initData '/Login Widget, მოკლემეტრაჟიანი პლატფორმის JWT გამოშვება.

4. Backend API პლატფორმები: პროფილი/საფულე/ტურნირები/მისიები/აფილიტები/საფორტეპიანო.

5. Event bus: ნოტიფიკაცია (Kafka/Redis Streams) - შეტყობინებების გაგზავნა ბოტით.

6. Observability & Security: WAF, mTLS ვებჰუკისთვის, საბინაო-ლიმიტი, აუდიტი, ალერტინგი.

SSO ნაკადი (მოკლედ):

3) ავტორიზაციის მეთოდები

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

Telegram შეცვლის 'initData' - ს WebApp- ში. თქვენ მას ხელს აწერთ HMAC-SHA256 სერვერზე, კლავიშით = ბორტ ტოკენი.

წარმატების მისაღწევად, გაათავისუფლეთ მოკლე JWT და (საჭიროების შემთხვევაში) დაუკავშირეთ Telegram ანგარიში არსებულ პროფილს.

შემოწმების ფსევდო კოდი 'initData':

python def verify_init_data(init_data: str, bot_token: str) -> dict:
init _ data - სტრიქონი 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 (მაგალითად, 10 წუთი)
assert now() - int(data['auth_date'][0]) < 600 return data

ბ) Telegram Login Widget (გარე გვერდი)

ვიჯეტი იძლევა 'id, first _ name, auth _ date, hash'. შემოწმება მსგავსია ('Telegram Login + bot _ token').

შესაფერისია, თუ არ იყენებთ WebApp- ს, მაგრამ შეიტანეთ ჩვეულებრივი ვებ - კაბინეტი.

4) ანგარიშის დაკავშირება და იდენტურობის მოდელი

პირველადი გასაღები: 'telegram _ user _ id' ('from. id`).

ჩვენ ვქმნით სავალდებულო ჩანაწერს: 'platform _ user _ id' telegram _ user _ id 'chat _ id' username (nullable) '+ თანხმობის ატრიბუტები.

ლინუქსის/უნლინკის სტრატეგიები:

ახალი მომხმარებელი - ჩვენ ვქმნით გამარტივებულ პროფილს, ვთხოვთ დაადასტუროს ტელეფონი/ელ.ფოსტა ოფისში.
არსებული deep-link '/start link: 'ან WebApp' s 'start _ param', ჩვენ ვხსნით მოდელს მითითებისთვის.
Unlink - პარამეტრების საშუალებით, დაუყოვნებლივ აცნობეთ შეტყობინებებს.

5) ვებჰუკ ბოტა: უსაფრთხოება და სტაბილურობა

HTTPS + ფიქსირებული დომენი, mTLS (თუ ეს შესაძლებელია) და მოქმედი საიდუმლო პატჩი ('/bot/< token> '), ან საკუთარი საიდუმლო სათაურში.

შეზღუდვა IP: whitelisting Telegram IP (თუ ინფრასტრუქტურა საშუალებას გაძლევთ), WAF წესები.

Idempotention: შეინარჩუნეთ 'განახლება _ id', დაამუშავეთ ზუსტად ერთხელ.

Retrai: Telegram იმეორებს 5xx/time - შეინარჩუნეთ მკურნალობა <1 s, მძიმე - რიგში.

Rate-limits: შეტყობინებების გაგზავნის ადგილობრივი ნიშნები (Telegram ზღუდავს სპამს), მასობრივი ფოსტის ხაზები.

დამუშავების ჩარჩოს მაგალითი:

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, დაწყების პარამეტრები და რეფერერი

ფორმის ბმული: 't. me/< bot>? start = '(base64url- ში 64 ბაიტი სასარგებლო მონაცემები).

გამოიყენეთ payload, როგორც ერთჯერადი nonce:

რეფრაქციული კამპანიები ('aff _ id', 'campaign _ id', 'click _ id'), დაუმთავრებელი ნაკადის გაგრძელება (KYC step, მისია, ტურნირი), ანგარიშის დაკავშირება.
შეინახეთ კორესპონდენცია 'nonce _ intended _ action' expires _ at ', გააკეთეთ single-use.
WebApp- ისთვის - არა. me//app? startapp = '(მიიღეთ' initData. start_param`).

7) Telegram WebApp: UX და ინტეგრაცია

TWA ფიჩები:

Тема (`themeParams`), mainButton/secondaryButton, BackButton, `HapticFeedback`, `expand()`, `viewport`.
ორმხრივი გაცვლა: 'Telegram. WebApp. sendAtata () 'ფრენა bota apdate- ში; ან WebApp იწვევს თქვენს Backend API- ს პირდაპირ მიღებულ JWT- სთან.

რეკომენდაციები:

მსუბუქი/ბნელი თემა ავტომატურად „themeParams“ - დან.
არ შეინახოთ 'initData' ბრაუზერში 10 წუთზე მეტხანს; განაახლეთ JWT refresh endpoint- ით (სერვერის სესიაზე).
დაამუშავეთ WebApp- ის დახურვა (მაგალითად, გაგზავნეთ მოქმედების დადასტურება ჩატში).
პატივს სცემთ WebView შეზღუდვებს: CSP, მხოლოდ https, ზომები, ფანჯრების გარეშე.

ინიციალიზაციის მინი მაგალითი:

js const tg = window. Telegram. WebApp;
tg. ready();
tg. expand();
const initData = tg. initData ;//გაგზავნეთ თქვენს პაკეტზე JWT tg- ზე გაცვლისთვის. MainButton. Settext ('გაგრძელება'). show(). onClick(() => submit());

8) ტიპიური flow

პროფილი/საფულე (ნახვა)

მომხმარებელი ხსნის WebApp- ს გადამოწმებას 'initData' - ს მიერ JWT- ს გაცემით და აჩვენებს ბალანსებს, საპასუხისმგებლო თამაშის KUS/ლიმიტების სტატუსებს, გარიგების ისტორიას (read-only).

ტურნირები/მისიები

TWA- ში ჩვენ ვაჩვენებთ ლიდერებს და მისიების პროგრესს (Real Time, მოკლე პოლინგი/WS უკანა პლანზე).

ღილაკები: „მონაწილეობა“, „გაზიარება“ (მეგობრებისთვის deep-link), „აცნობეთ დაწყებამდე 5 წუთით ადრე“.

შეტყობინებები

Event bus-consumer პლატფორმის მოვლენები ქმნის ტექსტს/inline კლავიატურას 'sendMessasse' s 'inline _ keyboard' (ბმული „გახსნა WebApp“ ან deep-link).

მხარი დაუჭირეთ opt/opt-out შეტყობინებების ტიპებს (ტურნირები, დასკვნა, პრემია).

საფორტი

სწრაფი პიკეტი/FAQ WebApp + ღილაკზე „გახსნა ჩატი ოპერატორთან“.

გადაამოწმეთ მომხმარებელი (SSO), აიღეთ ბოლო სესიის/ანაბრის კონტექსტები.

9) გადახდის და შესაბამისობის ასპექტები

ფულადი გარიგებები (ანაბრები/დასკვნები) - ვებ - ოფისში, რომელიც ღიაა ბოტიდან (URL ღილაკი) ან WebApp- დან (ღილაკი „გადადით ოფისში“).

TWA- ს შიგნით ნებადართულია უსაფრთხო read-only ოპერაციები და „მსუბუქი“ მოქმედებები (სავალდებულო, სარეკლამო გააქტიურება, ტურნირები).

კონფიდენციალურობა: არ წაიყვანოთ PII ჩეთში; აჩვენეთ იგი მხოლოდ WebApp- ის შიგნით (https, ავტორიზაცია).

თანხმობის ლოგოები, შენახვის პოლიტიკა, „მოცილების უფლება“ - პროფილში.

10) ანტიფროდი და დაცვა

სიახლის შემოწმება „auth _ date“ და დრო/ASN ანომალიები.

'telegram _ user _ id' და IP ლიმიტი მგრძნობიარე ოპერაციებისთვის (პრომო გააქტიურება, რეფერატი).

Deep-links დაცვა: ერთჯერადი ნიშნები, მოკლე TTL, მომხმარებლის/ჩატის ბმული.

მასობრივი ფოსტისთვის - batch + jitter, შემოწმება „გაცივდეს“ საჩივრების/ბლოკირების შესახებ.

ჩატის ფაილების/მედიის გადამოწმება (თუ დოკუმენტებს იღებთ): ჩამოტვირთეთ Bot API- ს მეშვეობით 'file _ id' მიხედვით, შეამოწმეთ ტიპი/ზომა/ვირუსები, შეინახეთ შესაბამისობაში.

11) დაკვირვება, ალერტები, ლიმიტები

მეტრიკა:

`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`.
კონვერტაცია: გახსნა - ავტორიზაცია - მიზნობრივი მოქმედება (მისია/ტურნირი/დაბრუნება ოფისში).

ალერტა:

ხელმოწერის გადამოწმების შეცდომა> X% 5 მმ
"FloodWait '/429 შეტყობინებების გაგზავნისას.
ზრდა 'deep _ link _ link' ან ერთჯერადი ნიშნების შეცდომები.

Logs: JSON 'trace _ id', 'telegram _ user _ id' (ფსევდონიმი), PII გარეშე; დაუკავშირდით პლატფორმის ტრეისებს.

12) API კონტრაქტები (ესკიზები)

'initData' - ის გაცვლა JWT- სთვის

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

პროფილი

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

შეტყობინებების ხელმოწერა

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

ბიულეტენი (შიდა მომსახურება)

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

13) UI მაგალითები ბოტაში

ტურნირის ინლაინ კლავიატურა

json
{
"inline_keyboard": [
[{„ტექსტი“: „ლიდერის გახსნა“, ვებ _ app „: {“ url „:“ https ://twa. example/contest? id = october“}], [{„ტექსტი „: „წესები „„, url“:“ https ://brand. com/contests/october/rules"}]
]
}

Reply კლავიატურა „მთავარი მენიუ“

პროფილი

ტურნირები და მისიები
პრემია და პრომო
მხარდაჭერა

14) მასშტაბები და წინააღმდეგობა

Webhook - ხაზის ხაზები (სახელმწიფო); ჰორიზონტალური მასშტაბები.

შეინახეთ „დიალოგის მდგომარეობა“ Redis/DB- ში (finite state machine per 'chat _ id').

სარეზერვო GetUndates მექანიზმი (გრძელი პოლინგი) მხოლოდ რბოლა/ფოლკლორისთვის.

შეზღუდეთ გაგზავნის სიჩქარე ('messages/sec') და ყალბი ფოსტის ზომა; ტალღის დამგეგმავი.

DR: ნიშნების/საიდუმლოებების ნაკრები, მეორადი webhook endpoint, „სწრაფი გადართვის“ სცენარი.

15) Prod List მზადყოფნა

Webhook HTTPS, Secret/MTLS, retry უსაფრთხოება, idempotence 'and'.
ხელმოწერის შემოწმება 'initData '/Login Widget, ახალი ფანჯარა, მოკლე JWT გაცვლა.
Link/unlink ანგარიში, შენახვა 'telegram _ user _ id '/' chat _ id', შეტყობინებების თანხმობა.
Deep-links/' startapp 'მხოლოდ ერთჯერადი, TTL და აუდიტი.
WebApp: თემა, ღილაკები, უკან, refresh JWT; CSP, https, PII გარეშე URL- ში.
ანტიფროდი: rate-limit, ASN/მარიონეტული სიგნალები, რეფერების დაცვა.
შეტყობინებები: რიგები, batch + jitter, FloodWait/429 მონიტორინგი.
დაკვირვება: მეტრიკა webhook/TWA/კონვერტაცია, ალერტები.
UX/შეზღუდვების დოკუმენტაცია, კონფიდენციალურობის პოლიტიკა, DPA Telegram- ით, როგორც არხი.
Runbook "და: webhook- ის ვარდნა, დუბლიკატების ვარდნა, მასობრივი FloodWait, TWA- ს უარყოფა.

რეზიუმე

Telegram- თან ინტეგრაცია არ არის „კიდევ ერთი ბოტი“, არამედ სრული არხი უსაფრთხო SSO (შემოწმება 'initData '/Login), სისუფთავე UX WebApp და Apdate- ის საიმედო სერვერის დამუშავება. შეინარჩუნეთ ფულადი ოპერაციები მთავარ განაცხადში, ხოლო Telegram- ში - ძლიერი თანამგზავრული სკრიპტები: პროფილი, ტურნირები, მისიები, ნოტიფიკაციები, საფორტეპიანო და რეფერალი. დაამატეთ ერთჯერადი deep-links, მოკლემეტრაჟიანი JWT, რიგები და დაკვირვება - და მიიღეთ სწრაფი, უსაფრთხო და გაზომილი ზრდის და შენარჩუნების არხი.