راهنمای راه‌اندازی ربات تلگرام در تله‌ران

Telerun — تله‌ران

تله‌ران بستری برای اجرای ربات‌های تلگرام فراهم می‌کند. بسته به قابلیت‌های محیط اجرا و تنظیمات پروژه، می‌توانید از روش‌های مختلفی برای دریافت و پردازش پیام‌ها و سایر رویدادهای تلگرام استفاده کنید.

دو روش اصلی دریافت به‌روزرسانی‌های تلگرام (Updates) عبارت‌اند از:

Webhook: تلگرام به‌روزرسانی‌های جدید را به یک نشانی اینترنتی مشخص ارسال می‌کند.
Polling: برنامه ربات به‌صورت دوره‌ای از Telegram Bot API درخواست می‌کند تا به‌روزرسانی‌های جدید را دریافت کند.

این راهنما نحوه آماده‌سازی کد ربات، انتخاب روش اجرا، تنظیم متغیرهای محیطی، پردازش داده‌های Telegram Mini App و عیب‌یابی مشکلات رایج را توضیح می‌دهد.

نکته: نحوه انتخاب روش اجرا، تنظیمات محیط اجرا و قرارداد موردنیاز برای تحویل Updateها به کد ربات باید با امکانات واقعی و مستندات جاری تله‌ران مطابقت داشته باشد. پیش از استقرار، تنظیمات مربوط به پروژه را در پنل تله‌ران بررسی کنید.

فهرست مطالب

مقدمه
Webhook و Polling چیست؟
مقایسه Webhook و Polling
انتخاب روش اجرا
راه‌اندازی Webhook
راه‌اندازی Polling
- Polling با aiogram
- Polling با python-telegram-bot
اتصال Telegram Mini App به ربات
مدیریت متغیرهای محیطی
ساختار پیشنهادی پروژه
عیب‌یابی
نکات امنیتی
چک‌لیست پیش از استقرار
جمع‌بندی

۱. مقدمه

ربات تلگرام برای دریافت پیام‌ها، اجرای دستورات و پاسخ‌گویی به کاربران، به سازوکاری برای دریافت Updateها نیاز دارد.

Update می‌تواند شامل موارد مختلفی باشد، از جمله:

پیام جدید
اجرای یک دستور
کلیک روی دکمه‌های تعاملی
Callback Query
اطلاعات ارسالی از Telegram Mini App
رویدادهای مرتبط با اعضای گروه
سایر رویدادهای پشتیبانی‌شده توسط Telegram Bot API

روش دریافت Updateها بر ساختار برنامه، مدیریت چرخه اجرا و نحوه استقرار ربات تأثیر می‌گذارد.

Webhook

در این روش، تلگرام Update را به یک نشانی HTTPS ارسال می‌کند. برنامه یا زیرساخت دریافت‌کننده، Update را پردازش می‌کند.

Polling

در این روش، برنامه ربات با استفاده از متد getUpdates در Telegram Bot API، Updateهای جدید را دریافت می‌کند.

در هر دو روش، منطق اصلی ربات در کد Python پیاده‌سازی می‌شود. تفاوت اصلی در نحوه دریافت Updateها و مدیریت چرخه اجرای برنامه است.

۲. Webhook و Polling چیست؟

۲.۱. Webhook

Webhook روشی برای دریافت رویدادها از طریق درخواست‌های ورودی HTTP است.

در معماری متداول Webhook:

یک نشانی اینترنتی برای دریافت Updateها تعیین می‌شود.
تلگرام Update جدید را به آن نشانی ارسال می‌کند.
دریافت‌کننده، داده را اعتبارسنجی و پردازش می‌کند.
ربات در صورت نیاز از Telegram Bot API برای ارسال پاسخ استفاده می‌کند.

در صورتی که محیط اجرای تله‌ران دریافت Updateها را مدیریت کند، ممکن است لازم باشد برنامه فقط Handlerها و منطق پردازش Update را ارائه دهد.

نکته مهم: این رفتار به قرارداد اجرای Webhook در تله‌ران بستگی دارد. مدیریت خودکار Webhook، نحوه کشف اشیای کتابخانه و قالب تابع پردازش Update باید از مستندات رسمی Runtime تأیید شود.

ویژگی‌های Webhook

دریافت Update از طریق درخواست ورودی
امکان استفاده از معماری رویدادمحور
عدم نیاز به حلقه Polling در برنامه‌ای که Runtime دریافت Update را مدیریت می‌کند
مناسب برای بسیاری از برنامه‌های عملیاتی
نیازمند پیکربندی صحیح نشانی Webhook و ارتباط امن
نیازمند مدیریت خطاها، درخواست‌های تکراری و پردازش قابل اعتماد

Webhook به‌خودی‌خود تضمین نمی‌کند که برنامه فقط هنگام دریافت پیام اجرا شود. این موضوع به معماری و نحوه میزبانی برنامه وابسته است.

۲.۲. Polling

در روش Polling، برنامه ربات درخواست دریافت Updateها را به Telegram Bot API ارسال می‌کند.

کتابخانه‌هایی مانند aiogram و python-telegram-bot ابزارهایی برای مدیریت این فرایند ارائه می‌دهند.

چرخه معمول Polling به این صورت است:

برنامه اجرا می‌شود.
اتصال لازم به Telegram Bot API برقرار می‌شود.
درخواست دریافت Update ارسال می‌شود.
Updateهای دریافتی به Handlerهای مربوط تحویل داده می‌شوند.
برنامه دریافت Updateهای بعدی را ادامه می‌دهد.

ویژگی‌های Polling

شروع دریافت Update از داخل برنامه
مناسب برای توسعه، آزمایش و برخی محیط‌های عملیاتی
نیازمند اجرای یک فرایند فعال
نیازمند مدیریت صحیح توقف و راه‌اندازی مجدد
وابسته به دسترسی برنامه به Telegram Bot API
امکان بروز تعارض در صورت اجرای هم‌زمان چند مصرف‌کننده برای یک ربات

در Polling، اجرای برنامه به‌تنهایی کافی نیست؛ کد باید دریافت Updateها را نیز آغاز کند.

۳. مقایسه Webhook و Polling

ویژگی	Webhook	Polling
روش دریافت Update	ارسال Update به نشانی Webhook	دریافت Update با درخواست `getUpdates`
شروع دریافت Update	از طریق زیرساخت Webhook	از طریق برنامه
مدیریت چرخه دریافت	وابسته به Runtime و چارچوب اجرا	معمولاً بر عهده برنامه و کتابخانه
نیاز به نشانی Webhook	بله	خیر
نیاز به `run_polling()`	در معماری Webhook نیازی نیست	در کتابخانه‌هایی که این متد را دارند، معمولاً بله
نیاز به `start_polling()`	در معماری Webhook نیازی نیست	در کتابخانه‌هایی که این متد را دارند، معمولاً بله
امکان اجرای مستقل برنامه	وابسته به معماری میزبانی	بله
ملاحظات اصلی	اعتبارسنجی درخواست، دسترس‌پذیری و مدیریت Update	اجرای مداوم، مدیریت اتصال و جلوگیری از مصرف‌کنندگان هم‌زمان
مناسب برای	معماری‌های مبتنی بر رویداد و Webhook	توسعه، آزمایش و برنامه‌های دارای فرایند مستقل

توجه: این جدول رفتار عمومی دو روش را مقایسه می‌کند. پشتیبانی هر روش، نحوه تنظیم آن و محدودیت‌های محیط اجرا باید در مستندات تله‌ران بررسی شود.

۴. انتخاب روش اجرا

انتخاب Webhook یا Polling به معماری برنامه، کتابخانه مورد استفاده و امکانات محیط میزبانی بستگی دارد.

۴.۱. چه زمانی Webhook مناسب است؟

Webhook می‌تواند انتخاب مناسبی باشد اگر:

زیرساخت میزبانی از دریافت Update از طریق Webhook پشتیبانی می‌کند.
می‌خواهید دریافت رویدادها از طریق درخواست‌های ورودی انجام شود.
معماری برنامه شما مبتنی بر پردازش رویدادها است.
می‌خواهید از قابلیت‌های مدیریت Webhook در محیط میزبانی استفاده کنید.
می‌خواهید دریافت Updateها از اجرای مستقل یک حلقه Polling جدا باشد.

پیش از انتخاب این روش، بررسی کنید که Runtime تله‌ران با کتابخانه و ساختار کد شما سازگار باشد.

۴.۲. چه زمانی Polling مناسب است؟

Polling می‌تواند انتخاب مناسبی باشد اگر:

در حال توسعه یا آزمایش ربات هستید.
برنامه باید به‌صورت یک فرایند مستقل اجرا شود.
کتابخانه انتخابی شما از Polling پشتیبانی می‌کند.
می‌خواهید مدیریت دریافت Update را مستقیماً در برنامه انجام دهید.
محیط میزبانی امکان اجرای مداوم فرایند را فراهم می‌کند.

اگر از Polling استفاده می‌کنید، مطمئن شوید فقط یک مصرف‌کننده فعال برای دریافت Updateهای همان ربات وجود دارد.

۴.۳. نکته درباره محیط اجرای تله‌ران

پیش از استقرار، تنظیمات پروژه را بررسی کنید و مطمئن شوید:

روش اجرای انتخاب‌شده با ساختار برنامه مطابقت دارد.
کتابخانه مورد استفاده با Runtime سازگار است.
متغیرهای محیطی موردنیاز تعریف شده‌اند.
وابستگی‌های پروژه نصب‌پذیر هستند.
روش اجرای برنامه با قراردادهای مستندشده در پنل مطابقت دارد.

۵. راه‌اندازی Webhook

ساختار برنامه در حالت Webhook به کتابخانه و نحوه ادغام آن با محیط میزبانی بستگی دارد.

در این بخش، دو کتابخانه رایج Python معرفی می‌شوند:

aiogram
python-telegram-bot

مهم: نمونه‌های این بخش برای معماری‌ای هستند که Runtime، Updateها را به Handlerهای برنامه تحویل می‌دهد. پیش از استفاده، تأیید کنید که Runtime تله‌ران دقیقاً از همین قرارداد پشتیبانی می‌کند.

۵.۱. Webhook با aiogram

در aiogram 3.x، شیء Bot برای تعامل با Telegram Bot API و شیء Dispatcher برای ثبت و اجرای Handlerها استفاده می‌شود.

اگر Runtime تله‌ران این اشیا را از ماژول برنامه شناسایی می‌کند، می‌توانید ساختار زیر را به کار ببرید.

نمونه کد

فایل main.py:

import logging
import os

from aiogram import Bot, Dispatcher, F
from aiogram.client.default import DefaultBotProperties
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message


logging.basicConfig(level=logging.INFO)

logger = logging.getLogger(__name__)

TOKEN = os.environ["TELEGRAM_TOKEN"]


# در این نمونه، اشیا در سطح ماژول ساخته می‌شوند.
bot = Bot(
    token=TOKEN,
    default=DefaultBotProperties(
        parse_mode=ParseMode.HTML
    ),
)

dp = Dispatcher()


@dp.message(CommandStart())
async def cmd_start(message: Message):
    await message.answer("سلام! 👋")


@dp.message(F.text & ~F.text.startswith("/"))
async def echo(message: Message):
    await message.answer(
        f"دریافت شد: {message.text}"
    )

نکات مهم

۱. ایجاد اشیا

در این نمونه، Bot و Dispatcher در سطح ماژول ایجاد شده‌اند.

این ساختار فقط زمانی مناسب است که Runtime تله‌ران همین اشیا را طبق قرارداد مستندشده شناسایی کند.

۲. شروع نکردن Polling

اگر Runtime خودش Updateها را به Dispatcher تحویل می‌دهد، نیازی نیست در همان برنامه Polling مستقلی اجرا کنید.

در چنین معماری‌ای، از فراخوانی موارد زیر خودداری کنید:

await dp.start_polling(bot)

۳. مدیریت Webhook

اگر Runtime مدیریت Webhook را بر عهده دارد، ایجاد یا حذف Webhook نباید بدون بررسی قرارداد محیط اجرا به کد اضافه شود.

۴. وابستگی‌ها

در صورت استفاده از این کتابخانه، وابستگی آن را در فایل requirements.txt ثبت کنید:

aiogram

برای استقرار قابل تکرار، بهتر است نسخه وابستگی‌ها را مطابق نسخه آزمایش‌شده پروژه تثبیت کنید.

۵.۲. Webhook با python-telegram-bot

کتابخانه python-telegram-bot امکاناتی برای ساخت برنامه، ثبت Handlerها و پردازش Updateها ارائه می‌دهد.

در معماری‌ای که Runtime، Updateها را به برنامه تحویل می‌دهد، می‌توانید از ساختار زیر استفاده کنید.

نمونه کد

فایل main.py:

import logging
import os

from telegram import Update
from telegram.ext import (
    ApplicationBuilder,
    CommandHandler,
    MessageHandler,
    ContextTypes,
    filters,
)


logging.basicConfig(level=logging.INFO)

logger = logging.getLogger(__name__)

TOKEN = os.environ["TELEGRAM_TOKEN"]


async def cmd_start(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
):
    if update.effective_message:
        await update.effective_message.reply_text(
            "سلام! 👋"
        )


async def echo(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
):
    message = update.effective_message

    if message and message.text:
        await message.reply_text(
            f"دریافت شد: {message.text}"
        )


# ساخت Application
app = ApplicationBuilder().token(TOKEN).build()

# ثبت Handlerها
app.add_handler(
    CommandHandler("start", cmd_start)
)

app.add_handler(
    MessageHandler(
        filters.TEXT & ~filters.COMMAND,
        echo,
    )
)

نکات مهم

در این نمونه، Application ساخته شده و Handlerها ثبت شده‌اند.
ساخت Application به‌تنهایی به معنی شروع دریافت Update نیست.
نحوه راه‌اندازی و آماده‌سازی Application به قرارداد Runtime بستگی دارد.
اگر Runtime مستقیماً از این ساختار پشتیبانی نمی‌کند، باید از روش ادغام مستندشده برای آن استفاده کنید.
در معماری Webhook مدیریت‌شده، نباید بدون بررسی مستندات، run_polling() یا run_webhook() را به‌صورت خودکار به کد اضافه کنید.

وابستگی این کتابخانه را در requirements.txt ثبت کنید:

python-telegram-bot

۵.۳. Webhook با سایر کتابخانه‌ها

اگر از کتابخانه‌ای غیر از aiogram یا python-telegram-bot استفاده می‌کنید، نحوه دریافت و پردازش Update باید با قرارداد محیط اجرا سازگار باشد.

برای نمونه، اگر مستندات Runtime تله‌ران اعلام می‌کنند که تابع زیر برای هر Update فراخوانی می‌شود، می‌توانید از یک Handler عمومی استفاده کنید:

async def handle_update(payload: dict):
    ...

بااین‌حال، نام تابع، نوع آرگومان، قالب داده و نحوه فراخوانی آن باید از مستندات رسمی Runtime تأیید شوند.

نمونه Handler عمومی

نمونه زیر یک تابع مستقل برای پردازش پیام‌های دریافتی نشان می‌دهد:

import logging

logger = logging.getLogger(__name__)


async def handle_update(payload: dict):
    """
    پردازش یک Telegram Update.

    این نمونه فقط زمانی قابل استفاده است که
    Runtime، Update را با همین قرارداد تحویل دهد.
    """

    message = payload.get("message")

    if not message:
        return

    chat = message.get("chat", {})
    chat_id = chat.get("id")
    text = message.get("text", "")

    logger.info(
        "Update received for chat_id=%s",
        chat_id,
    )

    if text == "/start":
        await send_message(
            chat_id,
            "سلام! 👋",
        )

در این نمونه، تابع send_message باید جداگانه پیاده‌سازی شود.

برای مثال، می‌توان از یک کتابخانه HTTP مانند httpx استفاده کرد.

import os

import httpx


async def send_message(
    chat_id: int,
    text: str,
):
    token = os.environ["TELEGRAM_TOKEN"]

    url = (
        f"https://api.telegram.org/"
        f"bot{token}/sendMessage"
    )

    async with httpx.AsyncClient() as client:
        response = await client.post(
            url,
            json={
                "chat_id": chat_id,
                "text": text,
            },
            timeout=15.0,
        )

        response.raise_for_status()

        result = response.json()

        if not result.get("ok"):
            raise RuntimeError(
                "Telegram API request failed"
            )

در صورت استفاده از این نمونه، وابستگی‌های لازم را ثبت کنید:

httpx

نکات مهم

payload باید مطابق ساختار Telegram Update پردازش شود.
وجود کلید message تضمین‌شده نیست؛ همه Updateها شامل پیام معمولی نیستند.
داده‌های ورودی را پیش از استفاده اعتبارسنجی کنید.
خطاهای HTTP و پاسخ‌های ناموفق Telegram Bot API را مدیریت کنید.
توکن ربات را در گزارش‌ها ثبت نکنید.
اگر Runtime قرارداد متفاوتی برای Handler دارد، این نمونه باید با همان قرارداد تطبیق داده شود.

۶. راه‌اندازی Polling

در Polling، برنامه باید دریافت Updateها را آغاز کند.

این روش با Webhook مدیریت‌شده تفاوت دارد؛ در Polling، کتابخانه معمولاً چرخه دریافت Update را در داخل فرایند برنامه مدیریت می‌کند.

۶.۱. Polling با aiogram

در aiogram 3.x می‌توانید از متد start_polling() برای دریافت Updateها استفاده کنید.

نمونه کد

فایل main.py:

import asyncio
import logging
import os

from aiogram import Bot, Dispatcher, F
from aiogram.client.default import DefaultBotProperties
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message


logging.basicConfig(level=logging.INFO)

logger = logging.getLogger(__name__)

TOKEN = os.environ["TELEGRAM_TOKEN"]


async def main():
    bot = Bot(
        token=TOKEN,
        default=DefaultBotProperties(
            parse_mode=ParseMode.HTML
        ),
    )

    dp = Dispatcher()

    @dp.message(CommandStart())
    async def cmd_start(message: Message):
        await message.answer("سلام! 👋")

    @dp.message(F.text & ~F.text.startswith("/"))
    async def echo(message: Message):
        await message.answer(
            f"دریافت شد: {message.text}"
        )

    try:
        # اگر Webhook قبلی فعال باشد،
        # پیش از Polling باید وضعیت آن تعیین تکلیف شود.
        await bot.delete_webhook(
            drop_pending_updates=False
        )

        # شروع دریافت Updateها
        await dp.start_polling(bot)

    finally:
        await bot.session.close()


if __name__ == "__main__":
    asyncio.run(main())

توضیحات

۱. شروع Polling

خط زیر چرخه دریافت Updateها را آغاز می‌کند:

await dp.start_polling(bot)

۲. حذف Webhook قبلی

Telegram Bot API اجازه نمی‌دهد Webhook و دریافت Update با getUpdates به‌صورت هم‌زمان برای یک ربات فعال باشند.

به همین دلیل، اگر ربات قبلاً از Webhook استفاده می‌کرده است، پیش از شروع Polling باید وضعیت آن مشخص شود.

در این نمونه:

await bot.delete_webhook(
    drop_pending_updates=False
)

Webhook قبلی حذف می‌شود و Updateهای در انتظار عمداً حذف نمی‌شوند.

اگر حذف Updateهای منتظر پردازش موردنظر شما نیست، از تنظیمی استفاده کنید که آن‌ها را حفظ می‌کند.

۳. مدیریت منابع

در پایان برنامه، نشست HTTP ربات بسته می‌شود تا منابع مرتبط آزاد شوند.

۴. جلوگیری از اجرای هم‌زمان

چند نمونه Polling مستقل را برای یک توکن اجرا نکنید؛ این کار می‌تواند باعث خطای تعارض در دریافت Updateها شود.

۶.۲. Polling با python-telegram-bot

در کتابخانه python-telegram-bot می‌توانید از run_polling() برای اجرای برنامه استفاده کنید.

نمونه کد

فایل main.py:

import logging
import os

from telegram import Update
from telegram.ext import (
    ApplicationBuilder,
    CommandHandler,
    MessageHandler,
    ContextTypes,
    filters,
)


logging.basicConfig(level=logging.INFO)

logger = logging.getLogger(__name__)

TOKEN = os.environ["TELEGRAM_TOKEN"]


async def cmd_start(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
):
    if update.effective_message:
        await update.effective_message.reply_text(
            "سلام! 👋"
        )


async def echo(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
):
    message = update.effective_message

    if message and message.text:
        await message.reply_text(
            f"دریافت شد: {message.text}"
        )


def main():
    app = (
        ApplicationBuilder()
        .token(TOKEN)
        .build()
    )

    app.add_handler(
        CommandHandler("start", cmd_start)
    )

    app.add_handler(
        MessageHandler(
            filters.TEXT & ~filters.COMMAND,
            echo,
        )
    )

    # شروع Polling و مدیریت چرخه اجرای برنامه
    app.run_polling(
        drop_pending_updates=False
    )


if __name__ == "__main__":
    main()

توضیحات

۱. شروع Polling

متد زیر چرخه دریافت Updateها و اجرای برنامه را مدیریت می‌کند:

app.run_polling(
    drop_pending_updates=False
)

۲. مدیریت چرخه اجرا

در این مثال، از asyncio.run() برای اجرای main() استفاده نشده است؛ زیرا run_polling() چرخه اجرای موردنیاز کتابخانه را مدیریت می‌کند.

۳. مدیریت Webhook قبلی

run_polling() در روند راه‌اندازی معمول خود، مراحل لازم برای شروع Polling را مدیریت می‌کند؛ از جمله پاک‌سازی Webhook در صورت نیاز، مطابق رفتار کتابخانه.

در این الگو، فراخوانی جداگانه و اجرا‌نشده‌ای مانند زیر اضافه نکنید:

app.bot.delete_webhook()

این متد ناهمگام است و فراخوانی آن بدون await در کد معمولی، به‌معنی تکمیل عملیات حذف Webhook نیست.

۴. وابستگی‌ها

در فایل requirements.txt:

python-telegram-bot

نسخه کتابخانه را متناسب با نسخه آزمایش‌شده پروژه تثبیت کنید.

۷. اتصال Telegram Mini App به ربات

Telegram Mini App امکان ساخت رابط‌های وب تعاملی را در محیط تلگرام فراهم می‌کند.

در برخی سناریوها، Mini App می‌تواند با استفاده از رابط JavaScript تلگرام، داده‌ای را به ربات ارسال کند.

یکی از روش‌های این کار، متد زیر است:

Telegram.WebApp.sendData()

این متد برای ارسال داده از Mini App به ربات در سناریوهای پشتیبانی‌شده طراحی شده است و جایگزین یک کانال ارتباطی عمومی و دائمی برای ارتباط دوطرفه نیست.

۷.۱. ارسال داده از Mini App

فرض کنید Mini App اطلاعات یک سفارش را ارسال می‌کند.

const payload = {
    action: "buy",
    item_id: 42,
    quantity: 2
};

Telegram.WebApp.sendData(
    JSON.stringify(payload)
);

از آنجا که sendData() داده را به‌صورت رشته دریافت می‌کند، برای ارسال یک شیء JavaScript معمولاً باید از JSON.stringify() استفاده کنید.

توجه: برای استفاده از sendData()، شرایط و محدودیت‌های رسمی Telegram Mini Apps را بررسی کنید. این متد برای همه انواع اجرای صفحه وب یا همه سناریوهای ارتباطی قابل استفاده نیست.

۷.۲. دریافت داده در aiogram

در aiogram می‌توانید از فیلد web_app_data برای شناسایی پیام‌های دارای داده Mini App استفاده کنید.

import json

from aiogram import F
from aiogram.types import Message


@dp.message(F.web_app_data)
async def on_web_app_data(message: Message):
    raw = message.web_app_data.data

    try:
        payload = json.loads(raw)

    except (json.JSONDecodeError, TypeError):
        await message.answer(
            "داده دریافتی معتبر نیست."
        )
        return

    if not isinstance(payload, dict):
        await message.answer(
            "ساختار داده نامعتبر است."
        )
        return

    action = payload.get("action")

    if action == "buy":
        quantity = payload.get("quantity")

        if (
            not isinstance(quantity, int)
            or isinstance(quantity, bool)
            or quantity < 1
        ):
            await message.answer(
                "تعداد سفارش معتبر نیست."
            )
            return

        await message.answer(
            f"درخواست سفارش برای {quantity} عدد دریافت شد."
        )

    else:
        await message.answer(
            "داده دریافت شد."
        )

نکات مهم

dp باید قبلاً ایجاد شده باشد.
Handler باید پیش از آغاز دریافت Update ثبت شود.
داده JSON باید پیش از استفاده اعتبارسنجی شود.
دریافت داده به‌تنهایی به معنی معتبر بودن سفارش یا مجاز بودن عملیات نیست.

۷.۳. دریافت داده در python-telegram-bot

در python-telegram-bot می‌توانید از فیلتر filters.StatusUpdate.WEB_APP_DATA استفاده کنید.

import json

from telegram import Update
from telegram.ext import (
    MessageHandler,
    ContextTypes,
    filters,
)


async def on_web_app_data(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
):
    message = update.effective_message

    if message is None or message.web_app_data is None:
        return

    raw = message.web_app_data.data

    try:
        payload = json.loads(raw)

    except (json.JSONDecodeError, TypeError):
        await message.reply_text(
            "داده دریافتی معتبر نیست."
        )
        return

    if not isinstance(payload, dict):
        await message.reply_text(
            "ساختار داده نامعتبر است."
        )
        return

    await message.reply_text(
        "داده Mini App دریافت شد."
    )


app.add_handler(
    MessageHandler(
        filters.StatusUpdate.WEB_APP_DATA,
        on_web_app_data,
    )
)

این Handler باید پس از ساخت app و پیش از آغاز دریافت Updateها ثبت شود.

۷.۴. نکات مهم امنیتی Mini App

داده دریافتی از Mini App را نباید به‌تنهایی مدرک هویت کاربر یا مجوز انجام عملیات حساس در نظر گرفت.

برای عملیات مهم مانند پرداخت، ثبت سفارش یا تغییر اطلاعات حساب:

داده‌های ورودی را اعتبارسنجی کنید.
هویت کاربر را با سازوکار مناسب سمت سرور بررسی کنید.
مجوز انجام عملیات را در سمت سرور تعیین کنید.
به مقادیر ارسالی از مرورگر برای تعیین قیمت یا سطح دسترسی اعتماد نکنید.
در صورت نیاز، داده احراز هویت Mini App را طبق مستندات رسمی تلگرام اعتبارسنجی کنید.

۸. مدیریت متغیرهای محیطی

اطلاعات حساس مانند توکن ربات نباید مستقیماً در کد منبع قرار گیرند.

برای این منظور، می‌توانید از متغیرهای محیطی استفاده کنید.

۸.۱. متغیر `TELEGRAM_TOKEN`

در نمونه‌های این راهنما، توکن ربات از متغیر زیر خوانده می‌شود:

TELEGRAM_TOKEN

در Python:

import os

TOKEN = os.environ["TELEGRAM_TOKEN"]

اگر متغیر تعریف نشده باشد، این دستور خطا ایجاد می‌کند. این رفتار می‌تواند از شروع برنامه با تنظیمات ناقص جلوگیری کند.

۸.۲. تعریف متغیر محیطی

در Linux یا محیط‌های مشابه، می‌توانید هنگام آزمایش محلی متغیر را به شکل زیر تعریف کنید:

export TELEGRAM_TOKEN="YOUR_BOT_TOKEN"

سپس برنامه را اجرا کنید:

python main.py

این روش برای آزمایش محلی مناسب است؛ اما برای محیط عملیاتی، بهتر است توکن را از طریق بخش مدیریت متغیرهای محیطی یا سازوکار مدیریت اسرار محیط میزبانی تنظیم کنید.

۸.۳. نمونه نادرست

TOKEN = "123456789:ABC..."

قرار دادن توکن در کد، خطر افشای آن را افزایش می‌دهد.

۸.۴. نمونه صحیح

import os

TOKEN = os.environ["TELEGRAM_TOKEN"]

۸.۵. نکات تکمیلی

توکن را در مخزن عمومی قرار ندهید.
توکن را در Logها چاپ نکنید.
از ارسال توکن در پیام‌های عمومی خودداری کنید.
فایل‌های حاوی اسرار را به مخزن Git اضافه نکنید.
در صورت افشای توکن، آن را از طریق سازوکار رسمی تلگرام تعویض کنید.

نام و نحوه تنظیم متغیرهای محیطی باید با امکانات واقعی پنل تله‌ران مطابقت داشته باشد.

۹. ساختار پیشنهادی پروژه

یک پروژه ساده Python می‌تواند ساختاری مشابه زیر داشته باشد:

my-bot/
├── main.py
├── requirements.txt
├── .gitignore
└── README.md

توضیح فایل‌ها

فایل	کاربرد
`main.py`	کد اصلی ربات و Handlerها
`requirements.txt`	وابستگی‌های Python
`.gitignore`	جلوگیری از ثبت فایل‌های غیرضروری و محرمانه در Git
`README.md`	توضیحات و دستورالعمل اجرای پروژه

نمونه `requirements.txt`

برای پروژه مبتنی بر aiogram:

aiogram

برای پروژه مبتنی بر python-telegram-bot:

python-telegram-bot

کتابخانه‌های اضافی، مانند httpx، فقط در صورت استفاده در پروژه باید اضافه شوند.

تثبیت نسخه وابستگی‌ها

برای استقرار قابل تکرار، نسخه وابستگی‌هایی را که در محیط توسعه آزمایش کرده‌اید مشخص کنید.

برای مثال، می‌توانید نسخه‌ها را با ابزار مدیریت وابستگی پروژه ثبت کنید یا از فایل قفل وابستگی‌ها استفاده کنید.

از نصب نسخه‌های ناسازگار با کد یا Runtime خودداری کنید.

۱۰. عیب‌یابی

این بخش مشکلات رایج هنگام راه‌اندازی ربات را بررسی می‌کند.

۱۰.۱. ربات پیام دریافت نمی‌کند

در Webhook

موارد زیر را بررسی کنید:

آیا روش اجرای انتخاب‌شده با کد پروژه مطابقت دارد؟
آیا توکن ربات معتبر است؟
آیا تنظیمات Webhook در محیط میزبانی صحیح هستند؟
آیا Runtime از کتابخانه مورد استفاده پشتیبانی می‌کند؟
آیا Handlerها به‌درستی ثبت شده‌اند؟
آیا خطایی در Logهای برنامه وجود دارد؟
آیا Update مورد انتظار در فهرست انواع Updateهای پشتیبانی‌شده قرار دارد؟

اگر پنل تله‌ران وضعیت Webhook یا خطاهای پردازش را نمایش می‌دهد، اطلاعات مربوط را نیز بررسی کنید.

در Polling

موارد زیر را بررسی کنید:

آیا فرایند برنامه در حال اجرا است؟
آیا start_polling() یا run_polling() فراخوانی شده است؟
آیا توکن صحیح است؟
آیا برنامه به Telegram Bot API دسترسی دارد؟
آیا خطای احراز هویت یا شبکه رخ داده است؟
آیا نمونه دیگری از ربات در حال دریافت Updateها است؟
آیا Handler مورد انتظار ثبت شده است؟

در صورت مشاهده خطا، ابتدا اولین خطای واقعی برنامه را بررسی کنید.

۱۰.۲. خطای `Conflict: terminated by other getUpdates request`

این خطا معمولاً زمانی رخ می‌دهد که بیش از یک مصرف‌کننده هم‌زمان برای دریافت Updateهای یک ربات از طریق getUpdates فعال باشد.

همچنین ممکن است تلاش برای استفاده از Polling در شرایطی که Webhook فعال است، باعث تعارض شود.

راه‌حل

نمونه‌های تکراری برنامه را متوقف کنید.
مطمئن شوید تنها یک مصرف‌کننده Polling فعال است.
اگر از Webhook به Polling تغییر می‌دهید، وضعیت Webhook را بررسی کنید.
از سازوکار صحیح کتابخانه برای شروع Polling استفاده کنید.

در aiogram:

await bot.delete_webhook(
    drop_pending_updates=False
)

await dp.start_polling(bot)

در python-telegram-bot، در صورت استفاده از الگوی معمول زیر، چرخه راه‌اندازی را به خود کتابخانه بسپارید:

app.run_polling(
    drop_pending_updates=False
)

از فراخوانی ناهمگام حذف Webhook بدون await خودداری کنید.

هشدار: برای رفع تعارض، لزوماً نیازی به حذف Updateهای منتظر پردازش نیست. گزینه drop_pending_updates=True باعث حذف Updateهای معوق می‌شود و باید فقط در صورت تصمیم آگاهانه استفاده شود.

۱۰.۳. خطای `runtime requires framework`

این خطا، در صورتی که از سوی Runtime تله‌ران گزارش شود، می‌تواند به ناسازگاری تنظیمات محیط اجرا با ساختار پروژه مربوط باشد.

موارد زیر را بررسی کنید:

آیا کتابخانه انتخاب‌شده در تنظیمات با کتابخانه استفاده‌شده در کد یکسان است؟
آیا وابستگی‌ها در requirements.txt ثبت شده‌اند؟
آیا ساختار برنامه مطابق قرارداد Runtime است؟
آیا نسخه کتابخانه با محیط اجرا سازگار است؟
آیا نقطه ورود برنامه مطابق مستندات تنظیم شده است؟

تفسیر دقیق این خطا باید بر اساس مستندات و پیام کامل خطای Runtime انجام شود.

۱۰.۴. برنامه شروع می‌شود، اما Handler اجرا نمی‌شود

موارد زیر را بررسی کنید:

آیا Handler پیش از آغاز دریافت Update ثبت شده است؟
آیا فیلتر Handler با نوع Update دریافتی مطابقت دارد؟
آیا پیام موردنظر از نوع پیام متنی است یا نوع دیگری از Update؟
آیا Exception در تابع Handler رخ می‌دهد؟
آیا Runtime، Update را مطابق قرارداد مورد انتظار تحویل می‌دهد؟

برای عیب‌یابی، می‌توانید Logهایی غیرحساس در ابتدای Handler ثبت کنید.

از ثبت توکن، اطلاعات احراز هویت و داده‌های شخصی غیرضروری خودداری کنید.

۱۰.۵. Mini App داده ارسال نمی‌کند

اگر داده ارسالی از Mini App دریافت نمی‌شود، موارد زیر را بررسی کنید:

۱. محیط اجرای Mini App

مطمئن شوید Mini App در محیطی اجرا می‌شود که API مربوط به Telegram Web Apps در آن در دسترس است.

۲. تبدیل داده به رشته

برای ارسال یک شیء JavaScript:

Telegram.WebApp.sendData(
    JSON.stringify(data)
);

۳. ثبت Handler مناسب

در aiogram:

@dp.message(F.web_app_data)

در python-telegram-bot:

filters.StatusUpdate.WEB_APP_DATA

۴. اعتبارسنجی داده

بررسی کنید که داده دریافتی JSON معتبر باشد و ساختار مورد انتظار برنامه را داشته باشد.

۵. بررسی شرایط API

مستندات رسمی Telegram Mini Apps را برای محدودیت‌های sendData() و شرایط استفاده از آن بررسی کنید.

۱۰.۶. برنامه به‌درستی متوقف نمی‌شود

اگر برنامه هنگام توقف با خطا مواجه می‌شود یا منابع آن آزاد نمی‌شوند، موارد زیر را بررسی کنید:

نحوه مدیریت وظایف ناهمگام
بسته‌شدن نشست‌های HTTP
مدیریت سیگنال‌های توقف
نحوه خاتمه فرایند در محیط میزبانی
وجود حلقه‌ها یا وظایف پس‌زمینه‌ای که به‌درستی متوقف نمی‌شوند

برای مدیریت منابع، از روش‌های توصیه‌شده کتابخانه مورد استفاده بهره بگیرید.

۱۱. نکات امنیتی

امنیت ربات به نحوه نگهداری اسرار، اعتبارسنجی ورودی‌ها، مدیریت دسترسی و پردازش درخواست‌ها وابسته است.

۱۱.۱. محافظت از توکن

توکن ربات را در کد منبع قرار ندهید.

روش پیشنهادی:

import os

TOKEN = os.environ["TELEGRAM_TOKEN"]

توکن نباید در Logها، مخزن عمومی یا پیام‌های قابل مشاهده برای دیگران ثبت شود.

۱۱.۲. اعتبارسنجی داده‌های ورودی

داده‌های دریافتی از کاربر یا Mini App باید غیرقابل اعتماد در نظر گرفته شوند.

برای مثال:

def validate_quantity(value):
    if not isinstance(value, int):
        return False

    if isinstance(value, bool):
        return False

    return value > 0

این تابع نمونه‌ای ساده از اعتبارسنجی مقدار عددی است. در برنامه واقعی، باید محدودیت‌های کسب‌وکار نیز بررسی شوند.

۱۱.۳. عملیات حساس

برای عملیات زیر، اعتبارسنجی سمت سرور ضروری است:

پرداخت
ثبت سفارش
تغییر سطح دسترسی
حذف اطلاعات
تغییر اطلاعات حساب
دسترسی به منابع خصوصی

داده‌ای که از رابط کاربری ارسال می‌شود، به‌تنهایی اثبات‌کننده مجاز بودن عملیات نیست.

۱۱.۴. امنیت Webhook

اگر خودتان زیرساخت Webhook را مدیریت می‌کنید، باید از سازوکارهای مناسب برای اعتبارسنجی درخواست‌های ورودی و حفاظت از Endpoint استفاده کنید.

در صورت استفاده از Webhook مدیریت‌شده توسط تله‌ران، مسئولیت‌ها و امکانات امنیتی دقیق باید از مستندات رسمی Runtime مشخص شوند.

بدون تأیید فنی، نباید ادعا کرد که تمام بررسی‌های امنیتی یا مدیریت Secret مربوط به Webhook به‌طور خودکار انجام می‌شوند.

۱۱.۵. امنیت Polling

در Polling نیز باید از توکن محافظت کنید و دسترسی به آن را محدود نگه دارید.

همچنین:

از اجرای نمونه‌های غیرضروری ربات خودداری کنید.
خطاهای شبکه و API را مدیریت کنید.
اطلاعات حساس را در گزارش‌ها ثبت نکنید.
برای Updateهای معوق، سیاست مشخصی داشته باشید.
وابستگی‌های پروژه را به‌صورت مسئولانه به‌روزرسانی کنید.

۱۲. چک‌لیست پیش از استقرار

پیش از اجرای ربات در محیط عملیاتی، موارد زیر را بررسی کنید.

۱۲.۱. تنظیمات عمومی

توکن ربات از طریق متغیر محیطی دریافت می‌شود.
وابستگی‌های پروژه در requirements.txt ثبت شده‌اند.
نسخه کتابخانه‌ها با کد پروژه سازگار است.
نقطه ورود برنامه مشخص است.
خطاهای برنامه قابل بررسی هستند.
اطلاعات محرمانه در Logها ثبت نمی‌شوند.
ورودی‌های کاربر اعتبارسنجی می‌شوند.

۱۲.۲. Webhook

محیط اجرا از روش Webhook مورد استفاده پشتیبانی می‌کند.
قرارداد Runtime با ساختار کد مطابقت دارد.
Handlerها به‌درستی ثبت شده‌اند.
مدیریت دریافت Update با معماری انتخاب‌شده سازگار است.
در صورت مدیریت Webhook توسط Runtime، از شروع Polling مستقل خودداری شده است.
تنظیمات و خطاهای Webhook بررسی شده‌اند.
عملیات حساس در سمت سرور اعتبارسنجی می‌شوند.

۱۲.۳. Polling

محیط اجرا امکان اجرای فرایند مستقل را فراهم می‌کند.
توکن از متغیر محیطی خوانده می‌شود.
start_polling() یا run_polling() مطابق کتابخانه فراخوانی می‌شود.
وضعیت Webhook قبلی بررسی شده است.
چند نمونه مستقل Polling برای یک ربات اجرا نمی‌شوند.
سیاست پردازش Updateهای معوق مشخص است.
منابع برنامه هنگام توقف آزاد می‌شوند.

۱۲.۴. Telegram Mini App

Mini App در محیط پشتیبانی‌شده اجرا می‌شود.
داده ارسالی با قالب مورد انتظار سازگار است.
داده JSON پیش از پردازش اعتبارسنجی می‌شود.
Handler مربوط به web_app_data ثبت شده است.
مجوز عملیات حساس در سمت سرور بررسی می‌شود.
داده دریافتی به‌عنوان مدرک مستقل هویت یا مجوز کاربر پذیرفته نمی‌شود.

۱۳. جمع‌بندی

تله‌ران بستری برای اجرای ربات‌های تلگرام فراهم می‌کند. انتخاب روش دریافت Updateها به معماری برنامه، کتابخانه مورد استفاده و قابلیت‌های محیط اجرا بستگی دارد.

Webhook

در Webhook، Updateها از طریق درخواست‌های ورودی به دریافت‌کننده تحویل داده می‌شوند.

در صورتی که Runtime تله‌ران از ادغام مستقیم با کتابخانه پشتیبانی کند، ممکن است لازم باشد فقط اشیا و Handlerهای موردنیاز را تعریف کنید.

بااین‌حال، نحوه شناسایی Bot، Dispatcher، Application یا تابع handle_update باید مطابق قرارداد رسمی Runtime باشد.

Polling

در Polling، برنامه دریافت Updateها را آغاز می‌کند.

در aiogram:

await dp.start_polling(bot)

در python-telegram-bot:

app.run_polling()

استفاده می‌شود.

در صورت تغییر از Webhook به Polling، باید تعارض میان دو روش دریافت Update برطرف شود. همچنین اجرای هم‌زمان چند مصرف‌کننده Polling برای یک ربات می‌تواند باعث بروز خطا شود.

Telegram Mini App

برای ارسال داده از Mini App به ربات می‌توان از این متد استفاده کرد:

Telegram.WebApp.sendData()

داده دریافتی باید در سمت سرور اعتبارسنجی شود و برای عملیات حساس نباید صرفاً به اطلاعات ارسالی از رابط کاربری اعتماد کرد.

مهم‌ترین نکات

روش اجرای برنامه را مطابق قابلیت‌های محیط میزبانی انتخاب کنید.
قرارداد Runtime تله‌ران را پیش از استفاده از الگوهای اختصاصی Webhook بررسی کنید.
توکن ربات را از طریق متغیر محیطی نگهداری کنید.
وابستگی‌های پروژه را ثبت و نسخه‌های سازگار را تثبیت کنید.
از اجرای هم‌زمان مصرف‌کنندگان Polling برای یک ربات جلوگیری کنید.
خطاها، ورودی‌ها و منابع برنامه را به‌درستی مدیریت کنید.
اطلاعات دریافتی از Mini App را در سمت سرور اعتبارسنجی کنید.

برای جزئیات مربوط به تنظیمات محیط اجرا، نحوه انتخاب چارچوب و قراردادهای اختصاصی پلتفرم، به مستندات رسمی تله‌ران و تنظیمات پروژه در پنل مراجعه کنید.

وب‌سایت رسمی: https://telerun.ir/

قبلیراهنمای امنیت و حفاظت از داده‌ها در تله‌ران

راهنمای راه‌اندازی ربات تلگرام در تله‌ران

فهرست مطالب

۱. مقدمه

Webhook

Polling

۲. Webhook و Polling چیست؟

۲.۱. Webhook

ویژگی‌های Webhook

۲.۲. Polling

ویژگی‌های Polling

۳. مقایسه Webhook و Polling

۴. انتخاب روش اجرا

۴.۱. چه زمانی Webhook مناسب است؟

۴.۲. چه زمانی Polling مناسب است؟

۴.۳. نکته درباره محیط اجرای تله‌ران

۵. راه‌اندازی Webhook

۵.۱. Webhook با aiogram

نمونه کد

نکات مهم

۵.۲. Webhook با python-telegram-bot

نمونه کد

نکات مهم

۵.۳. Webhook با سایر کتابخانه‌ها

نمونه Handler عمومی

نکات مهم

۶. راه‌اندازی Polling

۶.۱. Polling با aiogram

نمونه کد

توضیحات

۶.۲. Polling با python-telegram-bot

نمونه کد

توضیحات

۷. اتصال Telegram Mini App به ربات

۷.۱. ارسال داده از Mini App

۷.۲. دریافت داده در aiogram

نکات مهم

۷.۳. دریافت داده در python-telegram-bot

۷.۴. نکات مهم امنیتی Mini App

۸. مدیریت متغیرهای محیطی

۸.۱. متغیر TELEGRAM_TOKEN

۸.۲. تعریف متغیر محیطی

۸.۳. نمونه نادرست

۸.۴. نمونه صحیح

۸.۵. نکات تکمیلی

۹. ساختار پیشنهادی پروژه

توضیح فایل‌ها

نمونه requirements.txt

تثبیت نسخه وابستگی‌ها

۱۰. عیب‌یابی

۱۰.۱. ربات پیام دریافت نمی‌کند

در Webhook

در Polling

۱۰.۲. خطای Conflict: terminated by other getUpdates request

راه‌حل

۱۰.۳. خطای runtime requires framework

۱۰.۴. برنامه شروع می‌شود، اما Handler اجرا نمی‌شود

۱۰.۵. Mini App داده ارسال نمی‌کند

۱. محیط اجرای Mini App

۲. تبدیل داده به رشته

۳. ثبت Handler مناسب

۴. اعتبارسنجی داده

۵. بررسی شرایط API

۱۰.۶. برنامه به‌درستی متوقف نمی‌شود

۱۱. نکات امنیتی

۱۱.۱. محافظت از توکن

۱۱.۲. اعتبارسنجی داده‌های ورودی

۱۱.۳. عملیات حساس

۱۱.۴. امنیت Webhook

۱۱.۵. امنیت Polling

۱۲. چک‌لیست پیش از استقرار

۱۲.۱. تنظیمات عمومی

۱۲.۲. Webhook

۱۲.۳. Polling

۱۲.۴. Telegram Mini App

۱۳. جمع‌بندی

Webhook

Polling

Telegram Mini App

مهم‌ترین نکات

منوی بیشتر

۸.۱. متغیر `TELEGRAM_TOKEN`

نمونه `requirements.txt`

۱۰.۲. خطای `Conflict: terminated by other getUpdates request`

۱۰.۳. خطای `runtime requires framework`