Telegram Bot API

تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام

· 7 دقیقه مطالعه

برای تست مینی اپ تلگرام، اول رابط کاربری را در یک مرورگر معمولی با Telegram.WebApp شبیه‌سازی‌شده (mock) بسازید، بعد نسخه محلی را روی HTTPS در دسترس قرار دهید، آدرس را در @BotFather ثبت کنید و اپ را داخل تلگرام با DevTools باز کنید. قدم آخر در سرور است: قبل از اعتماد به کاربر، initData را اعتبارسنجی کنید. در ادامه کل این مسیر را از localhost تا چک‌لیست انتشار می‌بینید.

قدم 1: تست رابط کاربری در مرورگر معمولی

بیرون از تلگرام هیچ کلاینتی پشت Telegram.WebApp نیست: نه داده شروع، نه تم و نه دکمه‌های نیتیو. با این حال اگر کدتان این وضعیت را تحمل کند، بیشتر رابط کاربری را می‌توانید در مرورگر دسکتاپ بسازید:

const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);

if (insideTelegram) {
  tg.ready();   // placeholder بارگذاری را هر چه زودتر پنهان کن
  tg.expand();
} else {
  console.info("بیرون از تلگرام: استفاده از داده mock");
}

برای استایل از متغیرهای تم همراه با مقدار پیش‌فرض استفاده کنید، مثلاً var(--tg-theme-bg-color, #fff)، تا صفحه در هر دو محیط خوانا بماند.

برای دیدن کار هر متد بدون نوشتن کد، Mini App Tester را باز کنید. در مرورگر معمولی در حالت mock اجرا می‌شود و Telegram.WebApp را شبیه‌سازی می‌کند: MainButton و BackButton را بزنید، پاپ‌آپ باز کنید، در CloudStorage بنویسید، تم را عوض کنید و بیش از 45 رویداد را در لاگ ببینید. البته داده mock فقط جایگزین است: initData آن را تلگرام امضا نکرده و (به‌درستی) در اعتبارسنجی سمت سرور رد می‌شود.

قدم 2: اجرای مینی اپ تلگرام از localhost روی HTTPS

تلگرام مینی اپ را فقط از آدرس HTTPS باز می‌کند (به جز محیط تست) و گوشی شما هم اصلاً به http://localhost دسترسی ندارد. روش استاندارد تست مینی اپ تلگرام روی localhost، تونلی است که به سرور توسعه یک آدرس HTTPS عمومی می‌دهد:

# سرور توسعه را اجرا کنید، مثلاً Vite روی پورت 5173
npm run dev

# در ترمینال دوم، یکی از تونل‌ها را اجرا کنید
ngrok http 5173
cloudflared tunnel --url http://localhost:5173

هر کدام یک آدرس عمومی https:// چاپ می‌کند. دو مشکل رایج:

قدم 3: ثبت مینی اپ در @BotFather

مینی اپ همیشه به یک ربات تعلق دارد. اگر هنوز ربات ندارید، آموزش ساخت ربات تلگرام را دنبال کنید. بعد انتخاب کنید کاربر چطور آدرس شما را باز کند:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{"menu_button": {"type": "web_app", "text": "باز کردن اپ",
       "web_app": {"url": "https://your-tunnel.example.com"}}}'

بدون chat_id این درخواست دکمه منوی پیش‌فرض را برای همه کاربران تنظیم می‌کند. هر بار آدرس تونل عوض شد، به جای تایپ دوباره curl، درخواست را در متد setChatMenuButton در Bot API Tester تکرار کنید.

قدم 4: استفاده از محیط تست تلگرام

تلگرام یک محیط تست جداگانه دارد که در آن لینک مینی اپ می‌تواند HTTP ساده بدون TLS باشد؛ برای تست در شبکه محلی خیلی به کار می‌آید. این محیط حساب و ربات مخصوص خودش را لازم دارد:

داخل حساب تست با @BotFather ربات بسازید و درخواست‌ها را به https://api.telegram.org/bot<token>/test/METHOD_NAME بفرستید. محدودیت‌های flood آنجا بیشتر نمی‌شوند و حتی ممکن است سخت‌گیرانه‌تر باشند، پس جای تست بار (load test) نیست. راه‌اندازی کامل، همراه با سوییچ TEST در Bot API Tester ما، در راهنمای سرور تست تلگرام آمده است.

قدم 5: دیباگ مینی اپ داخل تلگرام

خیلی از باگ‌ها هیچ‌وقت در Chrome دیده نمی‌شوند و فقط در WebView واقعی ظاهر می‌شوند. خلاصه دستورالعمل رسمی Debug Mode for Mini Apps:

پلتفرمروش inspect
iOSده بار روی آیکون Settings بزنید و Allow Web View Inspection را فعال کنید؛ با USB وصل شوید و در Safari روی Mac منوی Develop → دستگاه خود را باز کنید.
AndroidUSB debugging را فعال کنید؛ در تنظیمات تلگرام تا پایین بروید، دو بار شماره نسخه را لمس کنید و نگه دارید و Enable WebView Debug را انتخاب کنید؛ در Chrome آدرس chrome://inspect/#devices را باز کنید.
Telegram Desktop (Windows، Linux)نسخه بتا را نصب کنید؛ Settings → Advanced → Experimental settings → Enable webview inspection؛ راست‌کلیک → Inspect.
Telegram برای macOSنسخه بتا را نصب کنید؛ پنج بار روی آیکون Settings کلیک کنید و Debug Mini Apps را فعال کنید؛ راست‌کلیک → Inspect Element.

برای مقایسه سریع کلاینت‌ها، آدرس https://telegram-bot-api.info/telegram-mini-app-tester.html را به عنوان URL مینی اپ یک ربات تست تنظیم کنید. داخل تلگرام، Mini App Tester از API واقعی استفاده می‌کند و version، platform، colorScheme، themeParams، safe areaها و همه رویدادهایی را که هر کلاینت می‌فرستد نشان می‌دهد. در کد خودتان، قابلیت‌های جدیدتر را با Telegram.WebApp.isVersionAtLeast("8.0") محدود کنید و فرض نکنید همه آخرین نسخه اپ را دارند.

قدم 6: اعتبارسنجی initData در سرور

Telegram.WebApp.initDataUnsafe فقط برای نمایش است. رشته خام Telegram.WebApp.initData را به بک‌اند بفرستید و آنجا بررسی کنید:

  1. query string را پارس کنید و hash را از آن جدا کنید.
  2. بقیه فیلدها را بر اساس حروف الفبا مرتب کنید و به صورت خطوط key=value با جداکننده \n به هم بچسبانید؛ این همان data_check_string است.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token) را حساب کنید.
  4. داده معتبر است اگر hex(HMAC_SHA256(key=secret_key, message=data_check_string)) با hash برابر باشد.
  5. با بررسی auth_date، داده‌های قدیمی را رد کنید.
import crypto from "node:crypto";

export function validateInitData(initData, botToken, maxAgeSec = 3600) {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash") ?? "";
  params.delete("hash");

  const dataCheckString = [...params.keys()].sort()
    .map((key) => `${key}=${params.get(key)}`)
    .join("\n");

  const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
  const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");

  const valid = hash.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
  const age = Date.now() / 1000 - Number(params.get("auth_date"));
  if (!valid || !(age <= maxAgeSec)) return null;

  return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}

در کلاینت، رشته را بدون تغییر بفرستید، مثلاً fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData })، و با توکن همان رباتی که اپ را باز کرده اعتبارسنجی کنید. اگر طرف سومی باید داده را بررسی کند ولی نباید توکن شما را بداند، می‌تواند طبق مستندات رسمی فیلد signature را با کلید عمومی Ed25519 تلگرام بررسی کند.

Bot API 10.2: محافظت origin در مینی اپ

در Bot API 10.2 فراخوانی متدهای مینی اپ از originهایی غیر از دامنه اصلی مینی اپ ممنوع شد و این محافظت از 20 جولای 2026 برای همه مینی اپ‌ها فعال است. در زمان تست، این موضوع وقتی دردسر می‌شود که اپ از آدرس تونل ثبت‌شده به هاست دیگری ریدایرکت کند، مثلاً دامنه staging یا صفحه لاگین: آنجا فراخوانی‌های Telegram.WebApp دیگر کار نمی‌کنند. کدی را که با تلگرام کار می‌کند روی دامنه ثبت‌شده نگه دارید و هر بار هاست تونل عوض شد آدرس را دوباره ثبت کنید. می‌توانید در تنظیمات Mini App در @BotFather این محافظت را غیرفعال کنید، اما آن وقت مسئولیت اینکه مینی اپ هیچ لینکی به سایت‌های غیرقابل‌اعتماد نداشته باشد با خودتان است.

چک‌لیست تست مینی اپ تلگرام

کد اعتبارسنجی به توکن ربات وابسته است، پس آن را مخفی نگه دارید: راهنمای گرفتن و محافظت از توکن ربات را ببینید. اگر همین بک‌اند آپدیت‌های ربات را هم دریافت می‌کند، سراغ آموزش وب هوک ربات تلگرام بروید. اگر به جای یک وب‌اپ کامل فقط یک بلوک تعاملی کوچک داخل پیام چت لازم دارید، ویجت‌های تلگرام را ببینید که در Bot API 10.4 اضافه شده‌اند.

پرسش‌های متداول

چطور مینی اپ تلگرام را روی localhost تست کنم؟

تلگرام مینی اپ را فقط از آدرس HTTPS باز می‌کند؛ پس سرور توسعه را با یک تونل HTTPS (مثلاً ngrok یا Cloudflare Tunnel) در دسترس قرار دهید و همان آدرس را در @BotFather یا با setChatMenuButton ثبت کنید. در محیط تست لینک HTTP ساده هم مجاز است.

آیا می‌شود مینی اپ تلگرام را بدون خود تلگرام تست کرد؟

تا حدی. مرورگر معمولی کلاینت تلگرام ندارد، پس به یک mock از Telegram.WebApp نیاز دارید؛ مثل حالت mock در Mini App Tester. initData واقعی، پاپ‌آپ‌های نیتیو و لرزش (haptics) فقط داخل تلگرام کار می‌کنند.

چطور DevTools را برای مینی اپ تلگرام باز کنم؟

در iOS گزینه Allow Web View Inspection را فعال کنید (ده بار روی Settings بزنید) و از منوی Develop در Safari استفاده کنید. در اندروید WebView Debug را در تنظیمات دیباگ تلگرام روشن کنید و chrome://inspect/#devices را باز کنید. در دسکتاپ و macOS از گزینه‌های inspect در نسخه‌های بتا استفاده کنید.

چرا اعتبارسنجی initData شکست می‌خورد؟

دلایل رایج: بررسی initDataUnsafe به جای رشته خام initData، استفاده از توکن ربات دیگر، URL-decode نکردن مقادیر، باقی ماندن hash در data-check string، جابه‌جا کردن کلید و پیام در HMAC یا تست با داده mock که تلگرام هرگز امضایش نکرده است.

چرا متدهای Telegram.WebApp روی دامنه دیگر کار نمی‌کنند؟

از Bot API 10.2، فراخوانی متدهای مینی اپ از originی غیر از دامنه خود مینی اپ مسدود می‌شود و این محافظت از 20 جولای 2026 برای همه مینی اپ‌ها فعال است. اپ را روی دامنه ثبت‌شده نگه دارید یا در @BotFather این محافظت را غیرفعال کنید.

آیا سرور تست جداگانه‌ای برای مینی اپ تلگرام وجود دارد؟

بله. محیط تست از production جداست: آنجا حساب و ربات جدید لازم دارید، درخواست‌های Bot API به https://api.telegram.org/bot<token>/test/METHOD_NAME می‌روند و لینک مینی اپ می‌تواند HTTP بدون TLS باشد.

ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

دیپلوی ربات تلگرام: راه‌اندازی روی VPS، داکر و هاست Serverless

آموزش دیپلوی و هاست ربات تلگرام: polling یا وب هوک، سرویس systemd روی VPS، داکر، Cloudflare Workers با secret_token و چک‌لیست راه‌اندازی.

Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجت‌ها، پیام‌های rich و ephemeral، حالت مهمان و بیشتر

تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجت‌های HTML، پیام‌های rich و ephemeral و حالت مهمان، همراه با مثال JSON.

خطاهای Telegram Bot API: معنی هر خطا و روش رفع آن

خطاهای ربات تلگرام به زبان ساده: 400 chat not found، 403 bot was blocked by the user، 409 Conflict و 429 retry_after؛ علت، راه حل و کد مدیریت خطا.

محدودیت‌های Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام

محدودیت‌های Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.

دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپ‌لینک /start

تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپ‌لینک /start و دستور /cmd@bot در گروه‌ها.

کیبورد ربات تلگرام: دکمه شیشه‌ای (inline keyboard)، دکمه‌های callback و reply keyboard

ساخت دکمه شیشه‌ای ربات تلگرام: inline keyboard با callback_data، پاسخ با answerCallbackQuery، ویرایش پیام بعد از کلیک، reply keyboard و ForceReply.

اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورک‌فلو و ارسال پیام

اتصال n8n به تلگرام: توکن ربات به عنوان Access Token، وب هوک Telegram Trigger روی HTTPS عمومی، ارسال پیام با چت آیدی و رفع خطاهای رایج.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئری‌ها

ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.

پرداخت با Telegram Stars در ربات: فاکتور، پیش‌پرداخت، بازپرداخت و اشتراک

دریافت پرداخت با استارز تلگرام در ربات: sendInvoice با ارز XTR، پاسخ به pre_checkout_query، successful_payment، بازپرداخت و اشتراک با کد پایتون و JS.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراک‌گذاری تلگرام.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

مثال‌های کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیش‌نمایش در مرورگر با ربات پایتون.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.