Telegram Mini App — راهنمای گام به گام
این چیست؟#
Telegram Mini App به مشتریان شما اجازه می‌دهد تا منوی دیجیتال رستوران را مستقیماً در داخل Telegram باز کنند — بدون نصب برنامه‌ها و بدون رفتن به مرورگر. منو به عنوان بخشی بومی از Telegram به نظر می‌رسد: با تم کاربر سازگار می‌شود، از دکمه «بازگشت» و حرکات پشتیبانی می‌کند.
مزایا#
- 📱 در داخل Telegram — مشتری نیازی به جابجایی به مرورگر ندارد
- 🎨 ظاهر بومی — رنگ‌ها، فونت‌ها و تم با Telegram سازگار می‌شوند
- 🔗 Deep Links — لینک مستقیم به منوی رستوران خاص
- 🌍 زبان خودکار — زبان از تنظیمات Telegram کاربر گرفته می‌شود
- 🍪 بدون کوکی‌ها — بنر کوکی در داخل Telegram نمایش داده نمی‌شود
شروع سریع#
مرحله 1 — ایجاد یک ربات#
BotFather@ را در Telegram باز کنید و ارسال کنید:
/newbot
- نام ربات را وارد کنید (مثلاً
Cenaly Menu Bot) - نام کاربری را وارد کنید (مثلاً
MeniMenuBot) — باید بهBotختم شود - Bot Token دریافت شده را ذخیره کنید (فرمت:
123456789:ABCdefGHI...)
چرا Bot Token لازم است؟#
Bot Token یک کلید مخفی برای مدیریت برنامه‌نویسی ربات از طریق Telegram Bot API است. برای تنظیمات پایه Mini App (مراحل 2–4) نیازی به آن نیست — همه چیز از طریق BotFather انجام می‌شود. اما اگر بخواهید:
- ارسال پیام به مشتریان — اطلاعیه‌ها درباره وضعیت سفارش، تخفیفات، پیام‌های خوش‌آمدگویی
- اضافه کردن دکمه‌های inline به پیام‌های ربات (مثلاً دکمه «📋 باز کردن منو» — به بخش زیر مراجعه کنید)
- ایجاد ربات Telegram برای دریافت سفارشات — ربات می‌تواند سفارشات را دریافت و پردازش کند
- تنظیم Webhook — دریافت رویدادها از Telegram (فشار دکمه‌ها، دستورات کاربران)
- ادغام با سیستم CRM یا POS — پردازش خودکار سفارشات از طریق ربات
مرحله 2 — ایجاد Mini App#
دستور زیر را به BotFather ارسال کنید:
/newapp
- ربات را انتخاب کنید از لیست
- Title — نام برنامه (مثلاً
Cenaly) - Description — توضیحات (مثلاً
Digital restaurant menu) - Photo — تصویر 640×640 px را بارگذاری کنید (آیکون برنامه)
- GIF — انیمیشن (اختیاری). برای رد کردن،
/emptyارسال کنید - Web App URL — آدرس برنامه مشتری خود را وارد کنید:
https://cenaly.com
- Short Name — نام کوتاه برای لینک (مثلاً
menu)
پس از این، لینک کاری به شکل زیر خواهید داشت:
https://t.me/YourBot/menu
مرحله 3 — افزودن دکمه «منو» به چت ربات#
به BotFather ارسال کنید:
/setmenubutton
- ربات را انتخاب کنید
- URL را ارسال کنید:
https://cenaly.com
- متن دکمه را وارد کنید (مثلاً
Open Menuیا📋 منو)
اکنون با باز کردن چت با ربات، دکمه‌ای در پایین صفحه ظاهر می‌شود که برنامه شما را باز می‌کند.
مرحله 4 — اجازه دادن به دامنه#
به BotFather ارسال کنید:
/setdomain
ربات را انتخاب کنید و دامنه را وارد کنید:
cenaly.com
این اجازه می‌دهد Telegram Web App بر روی دامنه شما و تمام زیر دامنه‌های آن کار کند (مثلاً locationid.cenaly.com).
Deep Links — لینک‌ها به رستوران خاص#
Telegram از پارامتر startapp پشتیبانی می‌کند که هنگام باز کردن به برنامه منتقل می‌شود. از آن برای لینک‌ها به رستوران خاص استفاده کنید:
| لینک | چه چیزی باز می‌شود |
|---|---|
t.me/YourBot/menu |
صفحه اصلی |
t.me/YourBot/menu?startapp=LOCATION_ID |
منوی رستوران خاص |
t.me/YourBot/menu?startapp=LOCATION_ID__ru |
منو به زبان روسی |
t.me/YourBot/menu?startapp=LOCATION_ID__en |
منو به زبان انگلیسی |
مثال‌ها#
اگر LOCATION_ID رستوران شما — lnc2w74z است:
https://t.me/YourBot/menu?startapp=lnc2w74z
https://t.me/YourBot/menu?startapp=lnc2w74z__ru
https://t.me/YourBot/menu?startapp=lnc2w74z__en
دکمه‌های Inline از ربات#
اگر ربات شما به مشتریان پیام ارسال می‌کند، می‌توانید دکمه inline اضافه کنید که منو را باز کند:
گزینه 1 — دکمه Web App (بلافاصله باز می‌شود)#
{
"inline_keyboard": [[{
"text": "📋 باز کردن منو",
"web_app": {
"url": "https://LOCATION_ID.cenaly.com/ru"
}
}]]
}
گزینه 2 — دکمه Deep Link#
{
"inline_keyboard": [[{
"text": "📋 باز کردن منو",
"url": "https://t.me/YourBot/menu?startapp=LOCATION_ID__ru"
}]]
}
چه چیزی به طور خودکار کار می‌کند#
پس از اتصال در داخل Telegram به طور خودکار فعال می‌شود:
| عملکرد | توضیحات |
|---|---|
| 🎨 تم | رنگ‌های برنامه با تم Telegram (روشن/تیره) سازگار می‌شوند |
| ◀️ دکمه «بازگشت» | دکمه بومی Telegram هنگام باز کردن کارت محصول ظاهر می‌شود |
| 📏 Viewport | برنامه به اندازه کامل صفحه کشیده می‌شود |
| 🔒 حفاظت از بسته شدن | حرکت عمودی به طور تصادفی برنامه را نمی‌بندد |
| 🌍 زبان خودکار | زبان از پروفایل Telegram تعیین می‌شود، اگر به صراحت تعیین نشده باشد |
| 🍪 کوکی‌ها | بنر کوکی در داخل Telegram نمایش داده نمی‌شود |
کدهای QR برای رستوران‌ها#
کدهای QR موجود با URL به شکل https://lnc2w74z.cenaly.com به طور معمول از طریق مرورگر کار خواهند کرد.
برای ادغام بیشتر با Telegram می‌توانید کد QR دوم با لینک به ربات را روی میزها قرار دهید:
https://t.me/YourBot/menu?startapp=lnc2w74z
بررسی عملکرد#
- لینک
https://t.me/YourBot/menuرا در تلفن باز کنید - Start را فشار دهید (اگر برای اولین بار ربات را باز می‌کنید)
- دکمه 📋 منو را در نوار پایین چت فشار دهید
- اطمینان حاصل کنید که برنامه باز شده و منو را بارگذاری کرده است
- سعی کنید لینک deep را باز کنید:
https://t.me/YourBot/menu?startapp=LOCATION_ID
مشکلات رایج#
| مشکل | راه‌حل |
|---|---|
| برنامه باز نمی‌شود | اطمینان حاصل کنید که دامنه cenaly.com از طریق /setdomain مجاز است |
| صفحه سفید | اطمینان حاصل کنید که Web App URL به صورت https://cenaly.com مشخص شده است (HTTPS الزامی است) |
startapp کار نمی‌کند |
فرمت را بررسی کنید: LOCATION_ID (بدون فاصله، کاراکترهای خاص). جداکننده برای زبان — دو زیرخط __ |
| تم اعمال نمی‌شود | Telegram Mini App SDK باید متصل باشد (برنامه مشتری را به‌روزرسانی کنید) |