प्लेटफॉर्म के साथ टेलीग्राम बॉट और वेबएपी का एकीकरण

1) आईगेमिंग में टेलीग्राम क्यों

पहुंच और प्रतिधारण: त्वरित धक्का संवाद (टूर्नामेंट/मिशन सूचनाएं, स्टेटस, प्रोमो)।

आसान लॉगिन: SSO टेलीग्राम लॉगिन विजेट/WebApp 'InitData' के माध्यम से एक पासवर्ड के बिना।

मिनी-क्लाइंट: देशी थीम/बटन और सुरक्षित संदर्भ हस्तांतरण के साथ टेलीग्राम के अंदर वेब ऐप।

💡 महत्वपूर्ण: बॉट के अंदर "गेम मैकेनिक्स फॉर मनी" स्थानांतरित न करें। एक साथी चैनल के रूप में टेलीग्राम का उपयोग करें: सूचना, प्रोफ़ाइल, सीयूएस/स्टेटस, टूर्नामेंट/लीडरबोर्ड, प्रोमो, समर्थन, रेफरल प्रवाह। मुद्रा लेनदेन - एक पूर्ण केवाईसी/एएमएल और पीएसपी के साथ एक वेब कैबिनेट/आवेदन में।

2) एकीकरण वास्तुकला

घटक:

1. टेलीग्राम बॉट (बॉट एपीआई): प्रोसेसिंग अपडेट (वेबहुक), कमांड/कीबोर्ड, डीप-लिंक '/स्टार्ट पेलोड '।

2. टेलीग्राम वेबऐप (TWA): टेलीग्राम (इन-ऐप वेबव्यू) के अंदर वेब पेज, 'initData' प्राप्त करता है और टेलीग्राम UI के साथ एकीकृत करता है।

3. Auth/SSO प्लेटफ़ॉर्म गेटवे: सिग्नेचर 'initData '/Login Widget का सत्यापन, अल्पकालिक प्लेटफ़ॉर्म JWT की रिलीज़।

4. बैकेंड एपीआई प्लेटफॉर्म: प्रोफाइल/वॉलेट/टूर्नामेंट/मिशन/सहयोगी/समर्थन।

5. घटना बस: सूचना (काफ्का/रेडिस स्ट्रीम्स) → बॉट द्वारा संदेश भेजना।

6. अवलोकन और सुरक्षा: WAF, mTLS से वेबहुक, दर-सीमा, ऑडिट, अलर्ट।

एसएसओ प्रवाह (लघु):

टेलीग्राम (वेबऐप/लॉगिन) → 'initData '/auth-payload → Auth गेटवे HMAC → JWT (5-15 मिनट) जारी करता है → JWT के साथ वेबएपी/बॉट कॉल प्लेटफॉर्म एपीआई।

3) प्राधिकरण के तरीके

A) टेलीग्राम WebApp ('विंडो। टेलीग्राम। WebApp ')

टेलीग्राम ने 'initData' in WebApp का विकल्प दिया। आप इसे HMAC-SHA256 सर्वर पर = बॉट टोकन कुंजी के साथ साइन इन करते हैं।

सफल होने पर, एक छोटा JWT जारी करें और (यदि आवश्यक हो) अपने टेलीग्राम खाते को एक मौजूदा प्रोफ़ाइल से लिंक करें।

सत्यापन छद्म कोड 'InitData':

अजगर def verify_init_data (init_data: str, bot_token: str) -> डिक्ट:
init_data - क्वेरी-लाइक स्ट्रिंग "की1 =.. और की2 ="।
डेटा = parse_qs (init_data)
hash_provided = डेटा। पॉप ('हैश') [0]
check_string = 'é n' .join ([f "{k} = {v [0]}") k के लिए सॉर्ट (डेटा)। कुंजियां ())])
गुप्त = hmac। नया (b "WebAppData", bot_token। एनकोड (), 'sha256')। पचाना ()
calc = hmac। नया (रहस्य, check_string। एनकोड (), 'sha256')। hexdigest ()
मुखर hmac। compare_digest (calc, hash_provided)
auth_date की ताजगी की जाँच करें (उदाहरण के लिए, ≤ 10 मिनट)
अब () - int (डेटा ['auth _ date'] [0] <600 रिटर्न डेटा

बी) टेलीग्राम लॉगिन विजेट (बाहरी पृष्ठ)

विजेट 'आईडी, first_name, auth_date, हैश' देता है। चेक समान है ('"टेलीग्राम लॉगिन" + bot_token')।

यदि आप WebApp का उपयोग नहीं कर रहे हैं, तो उपयुक्त है, लेकिन एक नियमित वेब कैबिनेट दर्

4) खाता लिंकिंग और पहचान मॉडल

प्राथमिक कुंजी: 'tailegram _ user _ id' ('से। id ')।

हम बाइंडिंग का रिकॉर्ड बनाते हैं: 'प्लेटफ़ॉर्म _ user _ id username (nullable)' + सहमति के गुण (विपणन/सूचनाएं)।

लिंक/अनलिंक रणनीतियाँ:

एक नया उपयोगकर्ता - एक सरलीकृत प्रोफ़ाइल बनाएं, कृपया कार्यालय में फोन/ई-मेल की पुष्टि करें।
मौजूदा डीप-लिंक → '/स्टार्ट लिंक: 'या' start _ param 'के साथ WebApp, बाइंडिंग के लिए मोडल खोलें।
अनलिंक - सेटिंग्स के माध्यम से, हम तुरंत सूचनाओं को धक्का देने की क्षमता को रद्द करते हैं।

5) वेबहुक बोट: सुरक्षा और स्थिरता

HTTPS + फिक्स्ड डोमेन, mTLS (यदि संभव हो) और वैध गुप्त पथ ('/बॉट/< टोकन> '), या हेडर में अपना रहस्य।

आईपी प्रतिबंध: व्हाइटलिस्टिंग टेलीग्राम आईपी (यदि बुनियादी ढांचा अनुमति देता है), डब्ल्यूएएफ नियम।

पहचान: 'अद्यतन _ id' रखें, प्रक्रिया ठीक एक बार।

रेट्राई: टेलीग्राम 5xx/timeout पर दोहराता है - प्रसंस्करण रखें <1 s, भारी - लाइन में।

दर-सीमा: संदेश भेजने के लिए स्थानीय टोकन-बाल्टी (टेलीग्राम सीमा स्पैम), बड़े पैमाने पर मेलिंग के लिए कतारें।

उदाहरण हैंडलर फ्रेमवर्क:

अजगर
@ app। पोस्ट ("/टेलीग्राम/वेबहुक ")
def on_update (u: अद्यतन):
अगर देखा गया (यू। update_id): वापसी "ठीक है"
कतार। प्रकाशित करें ("tg। अद्यतन," यू। json ()) # async उपभोग mark_seen (u)। update_id)
वापसी "ठीक है"

6) डीप-लिंक, स्टार्ट-पैरामीटर और रेफरल

संदर्भ देखें: 't. me/< bot>? प्रारंभ = <पेलोड> '(बेस64url में पेलोड के ~ 64 बाइट्स तक)।

के लिए एक बार अस्थायी रूप से पेलोड का उपयोग करें:

रेफरल अभियान ('aff _ id', 'change _ id', 'क्लिक _ id'), अधूरा प्रवाह (KYC चरण, मिशन, टूर्नामेंट), खाता लिंकिंग की निरंतरता।
आप अनुपालन रखते हैं 'नॉन → intended_action → expires_at', एकल-उपयोग करें।
WebApp के लिए - 't। me/< bot >/app? स्टार्टअप = <पेलोड> '(' initData में प्राप्त करें। start_param')।

7) टेलीग्राम वेब ऐप: यूएक्स और एकीकरण

फ़ीचर TWA:

Тема ('Params'), मेनबटन/सेकेंडरी बटन, बैकबटन, 'हैप्टिकफीडबैक', 'विस्तार ()', 'व्यूपोर्ट'।
द्विपक्षीय विनिमय: 'तार। WebApp। डेटा () ' बॉट अपडेट में आएगा; या WebApp आपके बैकेंड API को सीधे प्राप्त JWT के साथ कॉल करता है।

सिफारिशें:

' Params' से लाइट/डार्क थीम स्वचालित रूप से।
10 मिनट से अधिक समय तक ब्राउज़र में 'initData' संग्रहीत न करें; JWT को रिफ्रेश एंडपॉइंट (प्रति सर्वर सत्र) के साथ अपडेट करें।
WebApp को बंद करने की प्रक्रिया (उदाहरण के लिए, चैट पर कार्रवाई की पुष्टि भेजें)।
वेबव्यू प्रतिबंध का सम्मान करें: CSP, https केवल, आकार, कोई पॉप-अप नहीं।

इनिशियलाइजेशन मिनी-उदाहरण:

js const tg = विंडो। टेलीग्राम। WebApp;
tg। तैयार ();
tg। विस्तार ();
Const initData = tg। InitData ;//JWT tg के आदान-प्रदान के लिए अपने बैकएण्ड को भेजें। मेनबटन। सेटपाठ ('जारी रखें')। शो ()। ऑनक्लिक (() => जमा करें ();

8) विशिष्ट प्रवाह

प्रोफ़ाइल/बटुआ (दृश्य)

उपयोगकर्ता WebApp सत्यापन 'initData' खोलता है - एक JWT संतुलन, CUS स्टेटस/जिम्मेदार गेम लिमिट, लेनदेन इतिहास (केवल पढ़ा-लिखा) दिखाता है।

टूर्नामेंट/मिशन

TWA में, हम लीडरबोर्ड और मिशन प्रगति (वास्तविक समय, छोटे मतदान/बैकएंड के माध्यम से WS) दिखाते हैं।

बटन: "भाग लें", "साझा करें" (दोस्तों के लिए गहरी कड़ी), "शुरुआत से 5 मिनट पहले सूचित करें।"

नोटिस

प्लेटफ़ॉर्म इवेंट - इवेंट बस उपभोक्ता 'इनलाइन _ कीबोर्ड' (लिंक "ओपन वेबएपी" या डीप-लिंक) के साथ पाठ/इनलाइन कीबोर्ड 'संदेश' उत्पन्न करता है।

अधिसूचना प्रकारों (टूर्नामेंट, आउटपुट, बोनस) के लिए ऑप्ट-इन/ऑप्ट-आउट का समर्थन करें।

समर्थन

WebApp + में त्वरित टिकट/FAQ "ऑपरेटर के साथ चैट करें" बटन।

उपयोक्ता (एसएसओ) सत्यापित करें, पिछले सत्र/जमा के संदर्भ को कड़ा करें।

9) भुगतान और अनुपालन पहलू

मनी लेनदेन (जमा/निकासी) - एक वेब कैबिनेट को बॉट (URL बटन) या WebApp ("गो टू कैबिनेट" बटन) से खोला गया।

TWA के अंदर, सुरक्षित रीड-ओनली ऑपरेशन और "आसान" क्रियाओं (बाइंडिंग, प्रोमो सक्रियण, टूर्नामेंट) की अनुमति दें।

गोपनीयता: पीआईआई से चैट न करें; इसे केवल WebApp (https, प्राधिकरण) के अंदर दिखाएं।

सहमति लॉग, प्रतिधारण नीति, "हटाने का अधिकार" - प्रोफ़ाइल में।

10) एंटीफ्राड और सुरक्षा

'auth _ date' freshness और timezones/ASN विसंगतियों के लिए जाँच करें।

संवेदनशील संचालन के लिए 'टेलीग्राम _ user _ id' और आईपी द्वारा दर-सीमा (प्रोमो, रेफरल की सक्रियता)।

डीप-लिंक सुरक्षा: वन-टाइम टोकन, शॉर्ट टीटीएल, उपयोगकर्ता/चैट बाइंडिंग।

बड़े पैमाने पर मेलिंग के लिए - बैच + जिटर, शिकायतों/अवरोधन के लिए "कूल" की जांच करें।

चैट से फ़ाइलों/मीडिया का सत्यापन (यदि आप दस्तावेज़ स्वीकार करते हैं): 'फ़ाइल _ आईडी' द्वारा बॉट एपीआई के माध्यम से डाउनलोड करें, टाइप/साइज ़/वायरस की जाँच करें, अनुपालन लूप में स्टोर करें।

11) अवलोकन, अलर्ट, सीमा

मेट्रिक्स:

'tg _ webhook _ latency', 'webhook _ 5xx', 'कतार _ lag', 'send _ rate', 'flood _ went _ hits'।
SLI WebApp: 'auth _ verify _ rtt', 'jwt _ imse _ latency _ p95', 'api _ 4xx/5xx', 'leadbord _ rt'।
रूपांतरण: → प्राधिकरण → लक्ष्य कार्रवाई (मिशन/टूर्नामेंट/कार्यालय में वापसी) खोलना।

अलर्ट:

हस्ताक्षर सत्यापन त्रुटि> 5 मिनट में एक्स%
संदेश भेजते समय 'FloodWate '/429।
'deep _ link _ reuse' या एक बार टोकन त्रुटियों का विकास।

लॉग: 'ट्रेस _ आईडी', 'टेलीग्राम _ user _ id' (छद्म नाम) के साथ JSON, PII के बिना; प्लेटफ़ॉर्म पटरियों

12) एपीआई अनुबंध (रेखाचित्र)

JWT के लिए 'InitData' का आदान-प्रदान

http
POST/v1/tg/exchange
{"init_data": "<string>"}
→ 200 {"jwt ": "<अल्पकालिक>", "expires_in":900}

प्रोफ़ाइल

http
GET/v1/tg/me
प्राधिकरण: वाहक <jwt>
→ 200 {"user _ id":" u _ 123", "बैलेंस": [...], "kyc": {"स्तर": "मूल"}

अधिसूचना सदस्यता

http
POST/v1/tg/सहमति
{"प्रचार": सच, "टूर्नामेंट": सच, "भुगतान": सही}

वितरण (आंतरिक सेवा)

json
{
"टेम्पलेट": "टूर्नामेंट _ स्टार्ट", "वर्स": {"नाम": "हैलोवीन स्प्रिंट", "स्टार्ट _ इन": "5m"}, लक्ष्य ": [{" चैट _ आईडी ": 12345," user _ 123} "]
}

13) बॉट में यूआई के उदाहरण

इनलाइन कीबोर्ड "टूर्नामेंट"

json
{
"inline_keyboard": [
[{"पाठ ":" ओपन लीडबोर्ड ", "वेब _ ऐप ": {" url":" https ://twa। उदाहरण/प्रतियोगिता? id = अक्टूबर"}], [{"पाठ ": "नियम ", "url":" https ://brand। कॉम/प्रतियोगिता/अक्टूबर/नियम"}]
]
}

जवाब कुंजीपट "मुख्य मेनू"

प्रोफ़ाइल

टूर्नामेंट और मिशन
बोनस और प्रोमो
ग्राहक सहायता

14) पैमाना और दोष सहिष्णुता

वेबहुक → कतार → श्रमिक (स्टेटलेस); क्षैतिज पैमाने।

Redis/DB (परिमित राज्य मशीन प्रति 'चैट _ id') में "संवाद स्थिति" को संग्रहीत करें।
बैकअप तंत्र गेटअपडेट (लंबे मतदान) केवल डिबग/फोलबैक के लिए।
भेजने की गति ('संदेश/सेकंड') और ब्रंच मेलिंग के आकार को सीमित करें; तरंग योजनाकार।
DR: टोकन/सीक्रेट बैकअप, सेकेंडरी वेबहुक एंडपॉइंट, "क्विक स्विच" स्क्रिप्ट।

15) डिलीवरी चेकलिस्ट

वेबहुक HTTPS, गुप्त/mTLS, पुन: सुरक्षा, पहचान 'अद्यतन _ id'।
हस्ताक्षर 'initData '/लॉगिन विजेट, ताजगी विंडो, एक छोटे JWT के लिए विनिमय का सत्यापन।
लिंक/अनलिंक खाता, 'टेलीग्राम _ user _ id '/' चैट _ id' का भंडारण, सूचनाओं के लिए सहमति।
डीप-लिंक/' स्टार्टअप 'केवल डिस्पोजेबल, टीटीएल और ऑडिट।
WebApp: थीम, बटन, बैक, रिफ्रेश JWT; CSP, https, URL में कोई PII नहीं।
एंटी-फ्रॉड: रेट-लिमिट, एएसएन/प्रॉक्सी सिग्नल, रेफरल प्रोटेक्शन।
वितरण: कतारें, बैच + जिटर, FloodWait/429 निगरानी।
अवलोकन: वेबहुक/TWA/रूपांतरण मेट्रिक्स, अलर्ट।
यूएक्स/प्रतिबंध प्रलेखन, गोपनीयता नीति, एक चैनल के रूप में टेलीग्राम के साथ डीपीए।
रनबुक 'और: वेबहुक ड्रॉप, डुप्लिकेट स्पाइक, बड़े पैमाने पर फ्लोडवेट, टीडब्ल्यूए विफलता।

सारांश फिर से शुरू करें

टेलीग्राम के साथ एकीकरण "एक और बॉट" नहीं है, बल्कि सुरक्षित SSO (चेक 'initData '/Login), साफ UX WebApp और अपडेट के विश्वसनीय सर्वर प्रोसेसिंग के साथ एक पूर्ण चैनल है। मुख्य अनुप्रयोग में धन लेनदेन रखें, और टेलीग्राम में - मजबूत साथी परिदृश्य: प्रोफ़ाइल, टूर्नामेंट, मिशन, सूचनाएं, समर्थन और रेफरल। एक बार के गहरे लिंक, अल्पकालिक JWT, कतारें और अवलोकन जोड़ें - और एक तेज, सुरक्षित और औसत दर्जे का विकास और प्रतिधारण चैनल प्राप्त करें।