Telegram botlarının ve WebApp'in platformla entegrasyonu

1) Neden iGaming'de Telegram

Erişim ve elde tutma: hızlı push diyalogları (turnuva/görev bildirimleri, statüler, tanıtımlar).

Kolay giriş: Telegram ile SSO Giriş Widget/WebApp 'initData'bir şifre olmadan.

Mini istemci: Yerel tema/düğmeler ve güvenli bağlam aktarımı ile Telegram içinde WebApp.

💡 Önemli: Bot içinde "para için oyun mekaniği" transfer etmeyin. Telegram'ı bir eşlik kanalı olarak kullanın: bildirimler, profil, CUS/durumlar, turnuvalar/liderlik tabloları, promosyon, destek, yönlendirme akışı. Para işlemleri - tam bir KYC/AML ve PSP ile bir web kabininde/uygulamada.

2) Entegrasyon mimarisi

Bileşenler:

1. Telegram Bot (Bot API): işlem güncellemeleri (webhook), komutlar/klavyeler, deep-links'/start payload '.

2. Telegram WebApp (TWA): Telegram içindeki web sayfası (uygulama içi WebView), 'initData' alır ve Telegram UI ile bütünleşir.

3. Auth/SSO platform ağ geçidi: 'initData'/Login Widget imzasının doğrulanması, kısa ömürlü platform JWT'nin piyasaya sürülmesi.

4. Arka uç API platformları: profil/cüzdan/turnuvalar/görevler/bağlı kuruluşlar/destek.

5. Etkinlik veri yolu: bildirimler (Kafka/Redis Streams) - bot ile mesaj gönderme.

6. Gözlem ve Güvenlik: WAF, mTLS'den webhook'a, oran limiti, denetim, uyarı.

SSO akışı (kısa):

Telegram (WebApp/Login) - 'initData'/auth-payload - Auth gateway HMAC'yi kontrol eder - JWT'yi (5-15 dakika) sorunlar - WebApp/bot platform API'sini JWT ile çağırır.

3) Yetkilendirme yöntemleri

A) Telegram WebApp ('penceresi. Telgraf. WebApp ')

Telegram, WebApp'ta 'initData' yerine geçer. HMAC-SHA256 sunucusunda = bot belirteci anahtarıyla imzalarsınız.

Başarılı olursa, kısa bir JWT bırakın ve (gerekirse) Telegram hesabınızı mevcut bir profile bağlayın.

Doğrulama sözde kodu 'initData':

Python def verify_init_data (init_data: str, bot_token: str) -> dict:
init_data - sorgu benzeri dize "key1 =.. & key2 ="..
veri = parse_qs (init_data)
hash_provided = veri. pop ('hash') [0]
check_string ='\n '.join ([f "{k} = {v [0]}" for k in sorted (data. Anahtarlar ())])
gizli = hmac. new (b "WebAppData", bot_token. encode (), 'sha256'). sindirmek ()
Calc = hmac. yeni (gizli, check_string. encode (), 'sha256'). hexdigest ()
hmac iddia et. compare_digest (calc, hash_provided)
auth_date tazeliğini kontrol edin (örneğin, ≤ 10 dakika)
assert now () - int (data ['auth _ date'] [0]) <600 dönüş verisi

B) Telegram Giriş Widget'ı (harici sayfa)

Widget'id, first_name, auth_date, hash 'verir. Kontrol benzerdir ('"Telegram Login" + bot_token').

WebApp kullanmıyorsanız uygundur, ancak normal bir web dolabı girin.

4) Hesap bağlama ve kimlik modeli

Birincil anahtar: 'telegram _ user _ id' ('itibaren. id ').

Bağlama kaydı oluşturuyoruz: 'Platform _ user _ id username (nullable)' + rıza nitelikleri (pazarlama/bildirimler).

Link/unlink stratejileri:

Yeni bir kullanıcı - basitleştirilmiş bir profil oluşturun, lütfen ofisteki telefonu/e-postayı onaylayın.
Mevcut deep-link -'/start link: 'veya' start _ param'ile WebApp, bağlama için modal açın.
Unlink - ayarlar aracılığıyla, bildirimleri itme yeteneğini anında iptal ediyoruz.

5) Webhook Bot: Güvenlik ve Sürdürülebilirlik

HTTPS + sabit alan adı, mTLS (mümkünse) ve geçerli gizli yol ('/bot/< token> ') veya başlıkta kendi sırrı.

IP kısıtlaması: Telegram IP'yi beyaz listeye alma (altyapı izin veriyorsa), WAF kuralları.

Idempotence: 'update _ id' tutun, tam olarak bir kez işlem yapın.

Retrai: Telegram 5xx/timeout'ta tekrarlanır - işleme devam edin <1 s, ağır - satırda.

Hız sınırları: Mesaj göndermek için yerel belirteç kovaları (Telegram spam'i sınırlar), toplu postalar için kuyruklar.

Örnek işleyici çerçevesi:

python
@ app. Mesaj ("/telegram/webhook ")
Def on_update (u: Güncelleme):
görüldüğü takdirde (u. update_id): return'tamam "
kuyruk. yayınla ("tg. Güncellemeler,'u. json ()) # async tüketmek mark_seen (u. update_id)
dönüş'tamam "

6) Derin bağlantılar, başlangıç parametreleri ve yönlendirme

Referansı görüntüle: 't. me/< bot>? start = '(base64url'de ~ 64 bayta kadar payload).

Aşağıdakiler için yükü bir kerelik nonce olarak kullanın:

Yönlendirme kampanyaları ('aff _ id', 'campaign _ id', 'click _ id'), bitmemiş akışın devamı (KYC adımı, görev, turnuva), hesap bağlama.
Uyumluluğu koruyorsunuz 'nonce> intended_action expires_at', tek kullanımlık yapın.
WebApp için - 't. me/< bot >/app? Startapp = '(get in' initData. start_param').

7) Telegram WebApp: UX ve entegrasyon

Özellik TWA:

Тема ('theme' Parks '), mainButton/secondaryButton, BackButton,' HapticFeedback ',' expand () ',' viewport '.
İkili değişim: 'Telgraf. WebApp. SendData () '- bot güncellemesine gelecek; Veya WebApp, Backend API'nizi doğrudan alınan JWT ile çağırır.

Öneriler:

'Theme' Params'tan otomatik olarak açık/koyu tema.
Tarayıcıda 'initData'yı 10 dakikadan fazla saklamayın; JWT'yi bir yenileme uç noktasıyla güncelleyin (sunucu oturumu başına).
WebApp'ı kapatma işlemi (örneğin, sohbete eylem onayı gönderin).
WebView kısıtlamalarına saygı gösterin: CSP, yalnızca https, boyutlar, pop-up yok.

Başlatma mini örneği:

Js const tg = pencere. Telgraf. WebApp;
Tg. Hazır ();
Tg. genişlet ();
const initData = tg. InitData ;//JWT tg ile değiştirmek için arka ucunuza gönderin. MainButton. SetText ('Devam'). göstermek(). OnClick (() => submit ());

8) Tipik akış

Profil/Cüzdan (Görünüm)

Kullanıcı WebApp'ı açar - doğrulama 'initData' - bir JWT yayınlar - bakiyeler, CUS durumları/sorumlu oyun sınırları, işlem geçmişi (salt okunur) gösterir.

Turnuvalar/Görevler

TWA'da, liderlik tablolarını ve görev ilerlemesini (gerçek zamanlı, kısa yoklama/arka uç üzerinden WS) gösteririz.

Düğmeler: "Katıl", "Paylaş" (arkadaşlar için derin bağlantı), "Başlangıçtan 5 dakika önce bildir".

Bildirimler

Platform olayları, olay yolu, tüketici metin/satır içi klavye üretir, "inline _ keyboard'ile" sendMessage "(link" Open WebApp "veya deep-link).

Bildirim türleri (turnuvalar, çıktılar, bonuslar) için opt-in/opt-out desteği.

Destek

WebApp'ta hızlı bilet/SSS + "Operatörle sohbet aç" düğmesi.

Kullanıcıyı (SSO) doğrulayın, son oturumun/depozitonun bağlamını sıkın.

9) Ödeme ve uyumluluk yönleri

Para işlemleri (para yatırma/çekme) - bir bottan (URL düğmesi) veya WebApp'tan ("Kabine git" düğmesi) açılan bir web kabinine.

TWA'nın içinde, güvenli salt okunur işlemlere ve'kolay "eylemlere (bağlantılar, promosyon aktivasyonları, turnuvalar) izin verin.

Gizlilik: PII sohbet etmeyin; Sadece WebApp içinde göster (https, yetkilendirme).

İzin günlükleri, saklama politikası, "silme hakkı" - profilde.

10) Antifraud ve koruma

'Auth _ date' freshness and timezones/ASN anomalileri olup olmadığını kontrol edin.

Hassas işlemler için 'telegram _ user _ id've IP ile hız sınırı (promo aktivasyonu, yönlendirme).

Derin bağlantılar koruması: bir kerelik belirteçler, kısa TTL, kullanıcı/sohbet bağlama.

Toplu postalar için - batch + jitter, şikayet/engelleme için "cool" işaretleyin.

Sohbetlerden dosyaların/medyanın doğrulanması (belgeleri kabul ederseniz): Bot API aracılığıyla 'file _ id'ile indirin, türü/boyutu/virüsleri kontrol edin, bir uyumluluk döngüsünde saklayın.

11) Gözlemlenebilirlik, uyarılar, sınırlar

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'.
Dönüşüm: Açılış, yetkilendirme, hedef eylem (görev/turnuva/ofise dönüş).

Uyarılar:

İmza doğrulama hatası> 5 dakika içinde % X
'FloodWait'/429 mesaj gönderirken.
'Deep _ link _ reuse' veya bir kerelik belirteç hatalarının büyümesi.

Kayıtlar: 'trace _ id', 'telegram _ user _ id' (takma ad) ile JSON, PII olmadan; Platform parçaları ile ilişkilendirin.

12) API sözleşmeleri (eskizler)

JWT için 'initData' değişimi

http
POST/v1/tg/exchange
{"init_data": "<string>"}
^ 200 {"jwt ": "<kısa ömürlü>", "expires_in":900}

Profil

http
GET/v1/tg/me
Yetkilendirme: Taşıyıcı <jwt>
^ 200 {"user_id":"u_123," "dengeler": [...], "kyc ": {"seviye":" temel"}}

Bildirim abonelikleri

http
POST/v1/tg/consents
{"promosyonlar": doğru, "turnuvalar": doğru, "ödemeler": doğru}

Dağıtım (dahili hizmet)

Json
{
"şablon": "tournament _ start", "vars": {"name": "Halloween Sprint", "starts _ in": "5m"}, "targets": [{"chat _ id": 12345, "user _ id":'u _ 123 "}]
}

13) Bottaki UI örnekleri

Satır içi klavye "turnuvası"

Json
{
"inline_keyboard": [
[{"text ":" Open Leadboard ", "web _ app ": {" url":" https ://twa. Örnek/yarışma? id = october"}}], [{"text ": "Rules ", "url":" https ://brand. com/contests/october/rules"}]
]
}

Cevap-klavye "Ana menü"

Profil

Turnuvalar ve görevler
Bonuslar ve promosyonlar
Destek

14) Ölçek ve hata toleransı

Webhook - kuyruk - işçiler (vatansız); yatay ölçek.

Redis/DB'de "iletişim durumu'nu saklayın ('chat _ id' başına sonlu durum makinesi).

Yedekleme mekanizması getUpdates (uzun yoklama) sadece hata ayıklama/folback için.

Gönderme hızını ('mesajlar/sn') ve brunch postalarının boyutunu sınırlayın; dalga planlayıcısı.

DR: belirteç/gizli yedekleme, ikincil webhook uç noktası, "hızlı anahtar" komut dosyası.

15) Teslimat kontrol listesi

Webhook HTTPS, secret/mTLS, retry-security, idempotency 'update _ id'.
'initData'/Login Widget imzasının doğrulanması, tazelik penceresi, kısa bir JWT için değişim.
Link/unlink hesabı, depolama 'telegram _ user _ id'/' chat _ id', bildirimlere onay.
Derin bağlantılar/' startapp 'sadece tek kullanımlık, TTL ve denetim.
WebApp: tema, düğmeler, geri, JWT yenilemek; CSP, https, URL'de PII yok.
Anti-dolandırıcılık: oran limiti, ASN/proxy sinyalleri, tavsiye koruması.
Dağıtımlar: kuyruklar, batch + jitter, FloodWait/429 izleme.
Gözlemlenebilirlik: webhook/TWA/dönüşüm metrikleri, uyarılar.
UX/kısıtlama belgeleri, gizlilik politikası, Telegram ile kanal olarak DPA.
Runbook've: webhook damla, yinelenen başak, büyük FloodWait, TWA hatası.

Özgeçmiş Özeti

Telegram ile entegrasyon "başka bir bot'değil, güvenli SSO (check 'initData'/Login), temiz UX WebApp ve güncellemelerin güvenilir sunucu işlemesi ile tam teşekküllü bir kanaldır. Para işlemlerini ana uygulamada ve Telegram'da tutun - güçlü eşlik eden senaryolar: profil, turnuvalar, görevler, bildirimler, destek ve yönlendirme. Bir kerelik derin bağlantılar, kısa ömürlü JWT'ler, kuyruklar ve gözlemlenebilirlik ekleyin ve hızlı, güvenli ve ölçülebilir bir büyüme ve tutma kanalı elde edin.