ادغام ربات های Telegram و WebApp با پلت فرم

1) چرا تلگرام در iGaming

رسیدن و حفظ: گفتگوهای فشار سریع (اطلاعیه های مسابقات/ماموریت، وضعیت، تبلیغات).

ورود آسان: SSO از طریق Telegram ورود ویجت/WebApp 'initData' بدون رمز عبور.

Mini-client: WebApp در داخل تلگرام با تم/دکمه های بومی و انتقال ایمن زمینه.

💡 مهم: «مکانیک بازی برای پول» را در داخل ربات انتقال ندهید. استفاده از تلگرام به عنوان یک کانال همراه: اطلاعیه ها، مشخصات، CUS/وضعیت، مسابقات/مدیران، تبلیغی، پشتیبانی، جریان ارجاع. معاملات پولی - در یک کابینه وب/برنامه با KYC/AML کامل و PSP.

2) معماری ادغام

قطعات:

1. ربات تلگرام (ربات API): پردازش به روز رسانی (webhook), دستورات/صفحه کلید, عمیق لینک '/شروع payload '.

2. Telegram WebApp (TWA): صفحه وب در داخل Telegram (WebView درون برنامه)، initData را دریافت می کند و با رابط کاربری Telegram ادغام می شود.

3. دروازه پلت فرم Auth/SSO: تأیید امضای 'initData '/ویجت ورود، انتشار پلت فرم کوتاه مدت JWT.

4. سیستم عامل API باطن: مشخصات/کیف پول/مسابقات/ماموریت/وابسته/پشتیبانی.

5. اتوبوس رویداد: اطلاعیه ها (Kafka/Redis Streams) → ارسال پیام توسط ربات.

6. مشاهده و امنیت: WAF، mTLS به webhook، نرخ محدود، حسابرسی، هشدار.

جریان SSO (کوتاه):

Telegram (WebApp/Login) → 'initData '/auth-payload → دروازه Auth HMAC را بررسی می کند → مسائل JWT (5-15 دقیقه) → WebApp/ربات API پلت فرم را با JWT فراخوانی می کند.

3) روش های مجوز

A) Telegram WebApp ("پنجره. تلگرام. وب سایت ')

تلگرام جایگزین initData 'in WebApp می شود. شما آن را در سرور HMAC-SHA256 با کلید = bot token امضا می کنید.

در صورت موفقیت، یک JWT کوتاه را آزاد کنید و (در صورت لزوم) حساب Telegram خود را به یک نمایه موجود پیوند دهید.

اعتبارسنجی شبه کد 'initData':

پایتون def verify_init_data (init_data: str, bot_token: str) -> dict:
init_data - رشته «key1 =.. & key2 =»..
داده ها = parse_qs (init_data)
hash_provided = داده ها پاپ («هش») [0]
check_string = '\n '.join ([f «{k} = {v [0]}» برای k در مرتب شده (داده ها. کلید ()))
راز = HMAC جدید (b «WebAppData», bot_token. کد ()، 'sha256'). هضم ()
کالک = هماک جدید (مخفی، check_string. کد ()، 'sha256'). شش ضلعی ()
ادعا HMAC. compare_digest (کالک، hash_provided)
تازگی auth_date را چک کنید (مثلا ≤ ۱۰ دقیقه)
assert now () - int (data ['auth _ date'] [0]) <600 return data

ب) ویجت ورود به تلگرام (صفحه خارجی)

ویجت شناسه، first_name، auth_date، هش را می دهد. چک مشابه است («ورود به سیستم تلگرام» + bot_token').

مناسب اگر از WebApp استفاده نمی کنید، اما یک کابینت وب معمولی را وارد کنید.

4) ارتباط حساب و مدل هویت

کلید اصلی: "telegram _ user _ id" ("از. شناسه ').

ما رکورد اتصال را ایجاد می کنیم: 'platform _ user _ id نام کاربری (nullable)' + ویژگی های رضایت (بازاریابی/اطلاعیه ها).

استراتژی های پیوند/عدم پیوند:

کاربر جدید → ایجاد یک پروفایل ساده، لطفا تایید تلفن/ایمیل در دفتر.
پیوند عمیق →/پیوند آغاز موجود: 'یا WebApp با' start _ param '، مدال را برای اتصال باز کنید.
Unlink - از طریق تنظیمات، ما فورا توانایی فشار دادن اطلاعیه ها را لغو می کنیم.

5) Webhook Bot: ایمنی و پایداری

HTTPS + دامنه ثابت، mTLS (در صورت امکان) و مسیر مخفی معتبر ('/bot/< token> ')، یا راز خود را در هدر.

محدودیت IP: لیست سفید Telegram IP (اگر زیرساخت اجازه می دهد)، قوانین WAF.

Idempotence: نگه داشتن 'update _ id'، پردازش دقیقا یک بار.

Retrai: Telegram در 5xx/timeout تکرار می شود - پردازش <1 s، سنگین - در خط.

Rate-limits: token-buckets محلی برای ارسال پیام (Telegram spam را محدود می کند)، صف برای ارسال نامه های انبوه.

چارچوب مدیریت مثال:

پایتون
@app است. پست («/telegram/webhook »)
دف on_update (تو: به روز رسانی):
در صورت مشاهده (u. update_id): بازگشت «خوب»
صف. انتشار ("tg. به روز رسانی" شما. json () # async consume mark_seen (u. update_id)
بازگشت «خوب»

6) لینک های عمیق، پارامترهای شروع و ارجاع

مشاهده مرجع: 't. me/< bot>? شروع = '(تا ~ 64 بایت payload در base64url).

استفاده از payload به عنوان نانس یک بار برای:

کمپین های ارجاعی («aff _ id»، «campaign _ id»، «click _ id»)، ادامه جریان ناتمام (مرحله KYC، ماموریت، مسابقات)، پیوند حساب.
شما نگه داشتن nonce انطباق → intended_action → expires_at'، انجام یک بار استفاده کنید.
برای WebApp - 't. me/< bot >/app? startapp = '(وارد' initData شوید. start_param') است.

7) Telegram WebApp: UX و ادغام

ویژگی TWA:

Тема ('themeParams'), mainButton/secondaryButton, BackButton, 'HapticFeedback', 'expand ()', 'viewport'.
تبادل دوجانبه: "تلگرام. وب اپلیکیشن sendData () → در به روز رسانی ربات وارد خواهد شد ؛ یا WebApp API Backend خود را به طور مستقیم با JWT دریافت می کند.

توصیه ها:

تم روشن/تاریک به طور خودکار از 'themeParams'.
«initData» را بیش از 10 دقیقه در مرورگر ذخیره نکنید. به روز رسانی JWT با نقطه پایانی تازه (در هر جلسه سرور).
فرایند بستن WebApp (به عنوان مثال، ارسال تایید اقدام به چت).
به محدودیت های WebView احترام بگذارید: CSP، فقط https، اندازه ها، بدون پنجره های بازشو.

نمونه اولیه مینی مثال:

js const tg = پنجره تلگرام. وب سایت ؛
TG. آماده () ؛
TG. گسترش () ؛
const initData = tg. initData ؛//ارسال به باطن خود را به تبادل برای JWT TG. دکمه اصلی setText («ادامه»). نمایش () onClick () => submit ());

8) جریان معمولی

مشخصات/کیف پول (مشاهده)

کاربر WebApp → verification 'initData' → مسائل JWT → را نشان می دهد تعادل, وضعیت CUS/محدودیت بازی مسئول, تاریخ معامله (فقط خواندنی).

مسابقات/ماموریت ها

در TWA، ما مدیران و پیشرفت ماموریت را نشان می دهیم (زمان واقعی، نظرسنجی کوتاه/WS از طریق backend).

دکمه ها: «شرکت»، «اشتراک گذاری» (لینک عمیق برای دوستان)، «اطلاع 5 دقیقه قبل از شروع».

اطلاعیه ها

رویدادهای پلتفرم → event bus → consumer تولید متن/صفحه کلید درون خطی → 'sendMessage' با 'inline _ keyboard' (پیوند «Open WebApp» یا پیوند عمیق).

پشتیبانی از انتخاب کردن/انتخاب کردن برای انواع اطلاع رسانی (مسابقات، خروجی، پاداش).

پشتیبانی از سایت

بلیط سریع/پرسش و پاسخ در WebApp + «چت باز با اپراتور» را فشار دهید.

کاربر (SSO) را تأیید کنید، زمینه آخرین جلسه/سپرده را محکم کنید.

9) جنبه های پرداخت و انطباق

معاملات پول (سپرده/برداشت) - به یک کابینه وب باز از یک ربات (دکمه URL) و یا از WebApp («برو به کابینه» را فشار دهید).

در داخل TWA، اجازه عملیات فقط خواندنی امن و اقدامات «آسان» (اتصال، فعال سازی تبلیغی، مسابقات).

حریم خصوصی: PII چت نکنید ؛ آن را فقط در داخل WebApp نشان می دهد (https، مجوز).

سیاهههای مربوط به رضایت, سیاست حفظ, «حق حذف» - در مشخصات.

10) ضد انفجار و حفاظت

گزینه auth _ date 'freshness and timezones/ASN anomalies را تیک بزنید.

محدودیت نرخ توسط «telegram _ user _ id» و IP برای عملیات حساس (فعال سازی تبلیغی، ارجاع).

حفاظت از لینک های عمیق: نشانه های یک بار، TTL کوتاه، اتصال کاربر/چت.

برای ارسال نامه های دسته جمعی - دسته ای + jitter، بررسی «سرد» برای شکایات/مسدود کردن.

تأیید فایل ها/رسانه ها از چت ها (اگر اسناد را قبول می کنید): از طریق API Bot توسط «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 _ reuse» یا یک بار استفاده مجدد.

سیاهههای مربوط: JSON با 'ردیابی _ id'، 'telegram _ user _ id' (نام مستعار)، بدون PII ؛ ارتباط با آهنگ های پلت فرم.

12) قراردادهای API (طرح)

تبادل «initData» برای JWT

وب سایت
پست/v1/tg/تبادل
{"init_data": "<string>"}
→ 200 {"jwt ": "<short-lived>", "expires_in":900}

مشخصات فنی

وب سایت
دریافت/v1/tg/من
مجوز: حامل <jwt>
→ 200 {«user_id":"u_123,» «تعادل»: [...]، «kyc «: {«سطح»:» اساسی»}

اشتراک های اطلاع رسانی

وب سایت
پست/v1/tg/موافقت نامه ها
{«تبلیغات»: درست, «مسابقات»: درست, «پرداخت»: درست}

توزیع (خدمات داخلی)

جی سون
{
«template «: «tournament _ start», «vars «: {«name»:» Halloween Sprint «, «stars _ in»:» 5m»} «targets «: [{«chat _ id «: 12345», user _ id»:» u _ 123»}
}

13) نمونه هایی از UI در ربات

صفحه کلید درون خطی «مسابقات»

جی سون
{
"inline_keyboard": [
[{"text ":" Open Leadboard ", "web _ app ": {" url":" https ://twa. مثال/مسابقه id = october»}]، [{«text «: «Rules «، «url»:» https ://brand. کام/مسابقات/اکتبر/قوانین"}]
]
}

پاسخ صفحه کلید «منوی اصلی»

مشخصات فنی

مسابقات و ماموریت ها
جوایز و تبلیغات
پشتیبانی از مشتری

14) مقیاس و تحمل خطا

Webhook → صف → کارگران (بدون دولت); مقیاس افقی

«حالت گفتگو» را در Redis/DB (ماشین حالت محدود در هر «chat _ id») ذخیره کنید.

مکانیسم پشتیبان گیری getUpdates (نظرسنجی طولانی) فقط برای اشکال زدایی/folback.

محدود کردن سرعت ارسال ('پیام/ثانیه') و اندازه نامه های ارسالی ؛ برنامه ریز موج

DR: token/secret backup، نقطه پایانی وب سایت ثانویه، اسکریپت «سوئیچ سریع».

15) چک لیست تحویل

Webhook HTTPS, secret/mTLS, سعی مجدد امنیت, idempotency 'update _ id'.
تایید امضای 'initData '/ورود ویجت, پنجره طراوت, تبادل برای یک JWT کوتاه.
لینک/حساب unlink، ذخیره سازی 'telegram _ user _ id '/' chat _ id'، رضایت به اطلاعیه ها.
لینک های عمیق/« startapp »فقط یکبار مصرف، TTL و حسابرسی.
WebApp: موضوع، دکمه ها، پشت، تازه کردن JWT ؛ CSP، https، بدون PII در URL.
ضد تقلب: نرخ محدود، سیگنال ASN/پروکسی، حفاظت ارجاع.
توزیع: صف، دسته ای + jitter، نظارت بر FloodWait/429.
قابلیت مشاهده: webhook/TWA/معیارهای تبدیل، هشدارها.
مستندات UX/محدودیت، سیاست حفظ حریم خصوصی، DPA با Telegram به عنوان یک کانال.
Runbook 'و: افت webhook، سنبله تکراری، عظیم FloodWait، شکست TWA.

خلاصه رزومه

ادغام با Telegram «ربات دیگری» نیست، بلکه یک کانال کامل با SSO امن (چک initData/Login)، UX WebApp شسته و رفته و پردازش سرور قابل اعتماد به روز رسانی است. نگه داشتن معاملات پول در برنامه اصلی و در Telegram - سناریوهای همراه قوی: نمایه، مسابقات، مأموریت ها، اعلان ها، پشتیبانی و ارجاع. پیوندهای عمیق یک بار، JWT های کوتاه مدت، صف ها و مشاهده پذیری را اضافه کنید - و یک کانال رشد و نگهداری سریع، ایمن و قابل اندازه گیری دریافت کنید.