Интегратсияи ботҳои Telegram ва Web-App бо платформа

1) Чаро Telegram дар IGaming

Дастрасӣ ва нигоҳдорӣ: муколамаҳои тези тела (огоҳиномаҳои мусобиқа/миссия, статусҳо, таблиғот).

Вуруди осон: SSO тавассути Telegram Login Widge/Web

Мизоҷи хурд: Веб-апп дар дохили Telegram бо мавзӯъ/тугмаҳои ватанӣ ва интиқоли боэътимоди матн.

💡 Муҳим: "механикаи бозӣ барои пул" -ро дар дохили бот интиқол надиҳед. Telegram-ро ҳамчун канали шарик истифода баред: огоҳиҳо, профил, CUS/statuses, мусобиқаҳо/лидерҳо, таблиғот, дастгирӣ, ҷараёни муроҷиат. Амалиётҳои пулӣ - дар веб-кабинет/барнома бо KYC/AML ва PSP.

2) Меъмории ҳамгироӣ

Компонентҳо:

1. Telegram Bot (Bot API): навсозиҳои коркард (вебҳук), фармонҳо/клавиатура, пайвандҳои амиқ '/сарбории оғоз '.

2. Telegram Web

3. Шлюзи платформаи Auth/SSO: тафтиши имзои 'init- Data '/Виҷети вуруд, барориши платформаи кӯтоҳмуддати JWT.

4. Платформаҳои пушти API: профил/ҳамён/мусобиқаҳо/миссияҳо/филиалҳо/дастгирӣ.

5. Автобуси ҳодиса: огоҳиномаҳо (Kafka/Redis Streams) → фиристодани паёмҳо бо бот.

6. Назорат ва Амният: WAF, MTLS ба webhook, меъёри маҳдудият, аудит, ҳушдор.

Ҷараёни SSO (кӯтоҳ):

Telegram (Web

3) Усулҳои авторизатсия

A) Telegram Web-App ('тиреза. Телеграмма. Вебапп ')

Telegram ивазкунандаи 'in Data' in Web 'App. Шумо онро дар сервери HMAC-SHA256 бо тугмаи = bot токен имзо мекунед.

Дар сурати муваффақ шудан, JWT-и кӯтоҳ ва (агар лозим бошад) ҳисоби Telegram-и худро ба профили мавҷуда пайваст кунед.

Рамзи псевдо-и тасдиқкунандаи 'init-Data':

python def verify_init_data (init_data: str, bot_token: str) -> dict:
init_data - сатри ба дархост монанд "key1 =.. & key2 ="..
маълумот = parse_qs (init_data)
hash_provided = маълумот. поп ('hash') [0]
check_string = '\n '.join ([f "{k} = {v [0]}" барои k дар навъҳо (додаҳо). калидҳо ())])
махфӣ = hmac. нав (б "Web рамзгузорӣ (), 'sha256'). ҳазм ()
calc = hmac. нав (махфӣ, check_string. рамзгузорӣ (), 'sha256'). hexdigest ()
тасдиқ hmac. compare_digest (калк, hash_provided)
тозагии auth_date санҷед (масалан, ≤ 10 дақиқа)
ҳоло тасдиқ кунед () - int (маълумот ['auth _ date'] [0]) <600 маълумоти бозгашт

B) Виҷети вуруди Telegram (саҳифаи беруна)

Васеъкунӣ 'id, first_name, auth_date, hash' медиҳад. Санҷиш шабеҳ аст ('"Telegram Login" + bot_token').

Мувофиқ аст, агар шумо Web-App-ро истифода набаред, балки ба кабинети муқаррарии веб дохил шавед.

4) Пайвасти ҳисоб ва модели шахсият

Калиди асосӣ: 'telegram _ user _ id' ('аз. id ').

Мо сабти ҳатмиро эҷод мекунем: 'platform _ user _ id номи корбар (нулл)' + хусусиятҳои ризоият (маркетинг/огоҳиҳо).

Стратегияҳои пайванд/номуайян:

Корбари нав → профили соддакардашударо эҷод кунед, лутфан телефон/почтаи электрониро дар офис тасдиқ кунед.
Истиноди мавҷудаи чуқур → '/оғоз: 'ё Web-App бо' start _ param ', модалро барои ҳатмӣ кушоед.
Unlink - тавассути танзимот, мо фавран қобилияти пахш кардани огоҳиҳоро бекор мекунем.

5) Bot Webhook: Амният ва устуворӣ

HTTPS + домейни собит, mTLS (агар имконпазир бошад) ва роҳи махфии дуруст ('/bot/< token> ') ё сирри худ дар сарлавҳа.

Маҳдудияти IP: сафедкунии Telegram IP (агар инфрасохтор имкон диҳад), қоидаҳои WAF.

Idempotence: 'update _ id' -ро нигоҳ доред, як маротиба коркард кунед.

Retrai: Telegram дар 5xx/timeout такрор мешавад - коркарди <1 s, вазнин - дар навбат.

Меъёри маҳдудиятҳо: сатилҳои маҳаллӣ барои фиристодани паёмҳо (Telegram спамро маҳдуд мекунад), навбатҳо барои фиристодани омма.

Намунаи чаҳорчӯбаи дастӣ:

питон
@ барнома. пост ("/telegram/webhook ")
def on_update (u: Навсозӣ):
агар дида шавад (у. update_id): бозгашт "хуб"
навбат. нашр ("тг. навсозиҳо," у. json ()) # async истеъмол мекунад mark_seen (u. update_id)
бозгашт "хуб"

6) Истинодҳои амиқ, параметрҳои оғоз ва муроҷиат

Маълумотномаи намоиш: 't. me/< bot>? оғоз = <сарборӣ> '(то ~ 64 байт бори гарон дар базе64урл).

Истифодаи сарборӣ ҳамчун nonce якдафъаина барои:

маъракаҳои муроҷиатӣ ('aff _ id', 'campaign _ id', 'click _ id'), идомаи ҷараёни нотамом (қадами KYC, миссия, мусобиқа), пайвасткунии ҳисоб.
Шумо риояи 'nonce → intended_action → expires_at', якдафъаина истифода баред.
Барои Вебапп - 't. me/< bot >/app? startapp = '(маълумот гиред). start_param').

7) Telegram Web-App: UX ва ҳамгироӣ

Хусусияти TWA:

Тема ('Teme' Params '), тугмаи асосӣ/дуюмдараҷа, тугмаи бозгашт,' Фикру мулоҳизаҳо ',' васеъ кардан (), 'намоиш'.
Мубодилаи дуҷониба: 'Телеграм. Веб-апп. ирсоли маълумот () '→ ба навсозии бот мерасад; ё Вебапп API-и шуморо мустақиман бо JWT-и гирифташуда занг мезанад.

Тавсияҳо:

Мавзӯи рӯшноӣ/торик ба таври худкор аз 'мавзӯъ' Парамҳо.
'Маълумот' -ро дар браузер зиёда аз 10 дақиқа нигоҳ надоред; навсозии JWT бо нуқтаи навсозӣ (дар як ҷаласаи сервер).
Пӯшидани равандҳои Webapp (масалан, тасдиқи амалро барои сӯҳбат фиристед).
Эҳтиром ба маҳдудиятҳои Webview: CSP, танҳо https, андозаҳо, поп-ап.

Намунаи мини оғозёбӣ:

js const tg = тиреза. Телеграмма. Веб-Апп;
тг. тайёр ();
тг. васеъ кардан ();
const init .Data = tg. Маълумот ;//барои мубодила ба JWT tg ба пуштибони худ фиристед. Тугмаи асосӣ. Танзими матн ('Идома'). нишон (). on- Click (() => пешниҳод кардан ();

8) Ҷараёни маъмулӣ

Профил/Ҳамён (Намоиш)

Истифодабаранда Web

Мусобиқаҳо/миссияҳо

Дар TWA, мо пешсафон ва пешрафти миссияро нишон медиҳем (вақти воқеӣ, овоздиҳии кӯтоҳ/WS тавассути пуштибонӣ).

Тугмаҳо: "Иштирок кунед", "Мубодила" (пайванди амиқ барои дӯстон), "Огоҳ 5 дақиқа пеш аз оғоз".

Огоҳиҳо

Чорабиниҳои платформа → автобуси ҳодиса → истеъмолкунанда клавиатураи матнӣ/дохилӣ → 'ирсоли паём' -ро бо 'inline _ keyboard' (истиноди "Open Webapp" ё пайванди амиқ) тавлид мекунад.

Дастгирии дасткашӣ/дасткашӣ аз намудҳои огоҳинома (мусобиқаҳо, натиҷа, мукофотпулӣ).

Дастгирӣ

Чиптаи зуд/FAQ дар тугмаи Webapp + "Сӯҳбати кушод бо оператор".

Корвандро тафтиш кунед (SSO), контексти сессия/пасандози охиронро мустаҳкам кунед.

9) Ҷанбаҳои пардохт ва мувофиқат

Амалиётҳои пулӣ (пасандозҳо/бозпас гирифтан) - ба веб-кабинет, ки аз бот (тугмаи URL) ё аз тугмаи Web-App ("Гузаштан ба кабинет") кушода шудааст.

Дар дохили TWA, танҳо амалиёти бехатар барои хондан ва амалҳои "осон" (пайвастшавӣ, фаъолсозии таблиғот, мусобиқаҳо) иҷозат диҳед.

Махфият: PII-ро сӯҳбат накунед; онро танҳо дар дохили Web-App нишон диҳед (https, authorization).

Гузоришҳои ризоият, сиёсати нигоҳдорӣ, "ҳуқуқи нест кардан" - дар профил.

10) Антифрауд ва муҳофизат

Санҷиши 'auth _ date' ва вақтсанҷҳо/аномалияҳои ASN.

Меъёри маҳдудият аз ҷониби 'telegram _ user _ id' ва IP барои амалиёти ҳассос (фаъолсозии промо, муроҷиат).

Муҳофизати чуқур: аломатҳои яквақта, TTL кӯтоҳ, ҳатмии корбар/чат.

Барои фиристодани оммавӣ - партия + ҷиттер, шикоятҳо/блокро "хунук" санҷед.

Тафтиши файлҳо/ВАО аз чатҳо (агар шумо ҳуҷҷатҳоро қабул кунед): тавассути Bot API тавассути 'file _ id' зеркашӣ кунед, намуди/андоза/вирусҳоро санҷед, дар ҳалқаи мувофиқат нигоҳ доред.

11) Риоя, огоҳӣ, маҳдудиятҳо

Нишондиҳандаҳо:

'tg _ webhook _ latency', 'webhook _ 5xx', 'quue _ lag', 'send _ rate', 'flood _ wait _ hits'.
SLI Вебапп: 'auth _ verify _ муваффақият', 'jwt _ issue _ latency _ p95', 'api _ 4xx/5xx', 'leadboard _ rtt'.
Табдилдиҳӣ: кушодани → авторизатсия → амали мақсаднок (миссия/мусобиқа/бозгашт ба офис).

Огоҳиҳо:

Хатои санҷиши имзо> X% дар 5 дақиқа
'Интизор шавед '/429 ҳангоми фиристодани паёмҳо.
Афзоиши 'deep _ link _ reuse' ё хатогиҳои аломати яквақта.

Гузоришҳо: JSON бо 'trace _ id', 'telegram _ user _ id' (тахаллуси), бе PII; бо пайраҳаҳои платформа шарик шавед.

12) Шартномаҳои API (эскизҳо)

Биржаи 'маълумот' барои JWT

http
POST/v1/tg/мубодила
{"init_data": "<string>"}
→ 200 {"jwt ": "<кӯтоҳмуддат>", "expires_in":900}

Профил

http
GET/v1/tg/ман
Авторизатсия: Bearer <jwt>
→ 200 {"user_id":"u_123," "мувозинат": [...], "kyc ": {"сатҳ":" асосӣ"}}

Обунаҳои огоҳинома

http
POST/v1/tg/розигӣ
{"таблиғот": дуруст, "мусобиқаҳо": дуруст, "пардохтҳо": ҳақиқӣ}

Тақсимот (хидмати дохилӣ)

json
{
"қолаб ": "tournament _ start", "vars ": {"name":" Halloween Sprint ", "start _ in":" 5m"}, "ҳадафҳо ": [{"chat _ id ": 12345," user _ id":" u _ 123"}]
}

13) Намунаҳои UI дар бот

Клавиатураи Inline "мусобиқа"

json
{
"inline_keyboard": [
[{"матн ":" Leadboard Open ", "web _ app ": {" url":" https ://twa. намуна/озмун? id = october"}}], [{"text ": "Қоидаҳо ", "url":" https ://brand. com/озмунҳо/октябр/қоидаҳо"}]
]
}

Ҷавоб-клавиатураи "Менюи асосӣ"

Профил

Мусобиқаҳо ва миссияҳо
Бонусҳо ва аксияҳо
Дастгирии муштариён

14) Андозагирӣ ва таҳаммулпазирии гуноҳ

Webhook → навбат → коргарон (бешаҳрвандӣ); миқёси уфуқӣ.

"Ҳолати муколама" -ро дар Redis/DB нигоҳ доред (мошини ниҳоии давлатӣ барои 'chat _ id').

Механизми нусхабардории гет (овоздиҳии дароз) танҳо барои ислоҳи/folback.

Маҳдудияти суръати фиристодан ('паёмҳо/сек') ва андозаи фиристодани brunch; банақшагирии мавҷ.

DR: нусхаи эҳтиётии токен/махфӣ, нуқтаи дуюмдараҷаи webhook, скрипти "гузариши зуд".

15) Рӯйхати назорати таҳвил

Webhook HTTPS, махфӣ/MTLS, retry-security, idempotency 'update _ id'.
Тафтиши имзоҳои 'Инитлит '/Виҷети вуруд, равзанаи тару тоза, мубодила барои JWT кӯтоҳ.
Ҳисоби пайванд/номуайян, нигоҳдории 'telegram _ user _ id '/' chat _ id', розигӣ ба огоҳиҳо.
Истинодҳои амиқ/' startapp 'танҳо якдафъаина, TTL ва аудит.
Веб-апп: мавзӯъ, тугмаҳо, бозгашт, таровати JWT; CSP, https, PII дар URL нест.
Қаллобӣ: меъёри маҳдудият, сигналҳои ASN/прокси, ҳифзи муроҷиат.
Тақсимот: навбатҳо, партия + ҷиттер, FloodWait/429 мониторинг.
Мушоҳида: webhook/TWA/ченакҳои табдилдиҳӣ, огоҳиҳо.
Ҳуҷҷатҳои UX/маҳдудият, сиёсати махфият, DPA бо Telegram ҳамчун канал.
Дафтарчаи корӣ 'ва: тарки webhook, хӯшае такрорӣ, тӯфони азими тӯфон, нокомии TWA.

Хулосаи дубора

Интегратсия бо Telegram ин "боти дигар" нест, балки як канали мукаммал бо SSO-и бехатар (санҷиши 'init' Data '/Login), тозаи UX Webep ва коркарди боэътимоди сервер мебошад. Амалиёти пулиро дар аризаи асосӣ нигоҳ доред ва дар Telegram - сенарияҳои қавии шарик: профил, мусобиқаҳо, миссияҳо, огоҳиномаҳо, дастгирӣ ва муроҷиат. Пайвасти яквақтаи амиқ, JWT-ҳои кӯтоҳмуддат, навбатҳо ва мушоҳидаҳоро илова кунед ва канали босуръат, бехатар ва андозагиришавандаро гиред.