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

پیش‌نیازهای ساخت ربات تلگرام با پایتون

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

نصب Python و آشنایی با اجرای فایل‌های پایتونی؛
یک ویرایشگر کد مانند VS Code؛
اتصال اینترنت پایدار؛
توکن اختصاصی ربات از BotFather.

اگر هنوز با ساخت ابزارهای خط فرمان پایتون آشنا نیستید، آموزش ساخت ابزار خط فرمان با پایتون و Typer می‌تواند دید خوبی درباره نصب وابستگی‌ها و اجرای پروژه بدهد.

ساخت ربات در BotFather و دریافت توکن

در تلگرام عبارت @BotFather را جست‌وجو کنید و وارد حسابی شوید که علامت تأیید رسمی دارد. سپس دستور /newbot را بفرستید. BotFather ابتدا نام نمایشی ربات و بعد نام کاربری آن را می‌خواهد. نام کاربری باید به bot ختم شود و قبلاً توسط فرد دیگری انتخاب نشده باشد.

توکن ربات را ایمن نگه دارید

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

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

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

python -m venv .venv
.venv\Scripts\activate
pip install python-telegram-bot --upgrade

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

source .venv/bin/activate
pip install python-telegram-bot --upgrade

کتابخانه python-telegram-bot از نسخه‌های جدید API تلگرام پشتیبانی می‌کند و ساختار آن بر پایه برنامه‌نویسی ناهمگام است. بنابراین در نمونه کد از async و await استفاده خواهیم کرد.

چیدمان پیشنهادی فایل‌ها

برای پروژه کوچک، یک فایل اصلی و یک فایل تنظیمات کافی است. چیدمان پیشنهادی زیر خوانایی را حفظ می‌کند:

telegram-bot/
├── bot.py
├── .env
└── .gitignore

در فایل .gitignore نام .env و پوشه .venv را اضافه کنید تا اطلاعات محرمانه و فایل‌های محیط مجازی تصادفاً ارسال نشوند.

نوشتن اولین ربات تلگرام

فایل bot.py را بسازید. کد زیر به دستور شروع، پیام‌های متنی و دستور راهنما پاسخ می‌دهد:

import os
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, ContextTypes, filters

TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(
        "سلام! من ربات آموزشی شما هستم. یک پیام برایم بفرستید."
    )

async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(
        "دستورها:\n/start شروع کار\n/help نمایش راهنما"
    )

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    text = update.message.text
    await update.message.reply_text(f"پیام شما دریافت شد: {text}")

def main() -> None:
    if not TOKEN:
        raise RuntimeError("متغیر TELEGRAM_BOT_TOKEN تنظیم نشده است")

    application = Application.builder().token(TOKEN).build()
    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    application.run_polling()

if __name__ == "__main__":
    main()

اجرای برنامه و آزمایش پاسخ‌ها

در ترمینال، متغیر توکن را تنظیم کنید. در ویندوز PowerShell می‌توانید از این دستور استفاده کنید:

$env:TELEGRAM_BOT_TOKEN="توکن-ربات-شما"
python bot.py

در لینوکس یا macOS نیز دستور به شکل زیر است:

export TELEGRAM_BOT_TOKEN="توکن-ربات-شما"
python bot.py

حالا صفحه ربات را در تلگرام باز کنید، روی Start بزنید و یک پیام معمولی بفرستید. متد run_polling به‌طور پیوسته به تلگرام وصل می‌ماند و پیام‌های جدید را دریافت می‌کند. برای متوقف کردن برنامه، کلیدهای Ctrl+C را بزنید.

افزودن دکمه و قابلیت کاربردی به ربات

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

from telegram import InlineKeyboardButton, InlineKeyboardMarkup

async def menu(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    keyboard = [
        [InlineKeyboardButton("راهنما", callback_data="help")],
        [InlineKeyboardButton("درباره ربات", callback_data="about")],
    ]
    await update.message.reply_text(
        "یک گزینه را انتخاب کنید:",
        reply_markup=InlineKeyboardMarkup(keyboard),
    )

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

ذخیره اطلاعات کاربر

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

مقایسه روش‌های اجرای دائمی ربات

تا زمانی که ترمینال باز است، polling کار می‌کند؛ اما برای استفاده عمومی باید روش اجرای مناسبی انتخاب کنید.

روش	مناسب برای	مزیت	نکته مهم
رایانه شخصی	یادگیری و آزمایش	رایگان و سریع	با خاموش شدن سیستم متوقف می‌شود
VPS لینوکس	ربات‌های کوچک و متوسط	کنترل کامل و اجرای دائمی	نیازمند مدیریت امنیت و به‌روزرسانی است
پلتفرم ابری	نمونه‌های قابل توسعه	استقرار آسان و مقیاس‌پذیری	ممکن است محدودیت رایگان داشته باشد
Webhook	ترافیک زیاد و پاسخ سریع	دریافت رویداد بدون اتصال دائمی	به دامنه و گواهی HTTPS نیاز دارد

برای شروع، polling انتخاب ساده‌تری است. وقتی ربات کاربر بیشتری پیدا کرد، می‌توانید آن را روی VPS اجرا کنید یا به webhook مهاجرت کنید. اگر هدف شما ساخت یک ابزار داده‌محور است، ایده‌های ساخت داشبورد شخصی هزینه‌ها با پایتون هم می‌تواند برای افزودن گزارش و نمودار به ربات الهام‌بخش باشد.

حل خطاهای رایج در ربات تلگرام

خطای توکن یا پاسخ نگرفتن از تلگرام

مقدار توکن را دوباره از BotFather کپی کنید و مطمئن شوید فاصله اضافی در ابتدا و انتهای آن وجود ندارد. اگر متغیر محیطی را در یک پنجره ترمینال تنظیم کرده‌اید، برنامه را در همان پنجره اجرا کنید. همچنین بررسی کنید اینترنت یا فایروال دسترسی پایتون به شبکه را مسدود نکرده باشد.

ربات به پیام‌ها پاسخ نمی‌دهد

مطمئن شوید برنامه هنوز در حال اجراست و خطایی در ترمینال نمایش داده نمی‌شود. در گروه‌ها، تنظیمات Privacy Mode روی رفتار ربات اثر می‌گذارد و ممکن است ربات همه پیام‌ها را نبیند. برای آزمایش اولیه، ربات را در گفت‌وگوی خصوصی امتحان کنید.

پیام تکراری یا چند پاسخ دریافت می‌کنم

احتمالاً فایل را بیش از یک بار اجرا کرده‌اید. هر نمونه فعال، پیام‌ها را دنبال می‌کند و می‌تواند باعث رفتار غیرمنتظره شود. پردازش‌های قدیمی را ببندید و تنها یک نمونه از برنامه را اجرا کنید.

نکات امنیتی و مرحله بعدی توسعه

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

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

سوالات متداول

آیا ساخت ربات تلگرام با پایتون رایگان است؟

ساخت ربات و استفاده از BotFather رایگان است. برای اجرای دائمی، می‌توانید از رایانه خودتان استفاده کنید یا یک سرویس ابری و VPS تهیه کنید که هزینه آن به منابع موردنیاز بستگی دارد.

آیا بدون سرور هم می‌توان ربات را اجرا کرد؟

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

Polling بهتر است یا Webhook؟

برای پروژه‌های آموزشی و ربات‌های کم‌ترافیک، polling ساده‌تر است. webhook برای استقرار حرفه‌ای، پاسخ سریع و کاهش اتصال‌های مداوم مناسب‌تر است، اما به دامنه و HTTPS نیاز دارد.

با همین اسکلت می‌توانید یک ربات تلگرام واقعی بسازید و قابلیت‌های آن را قدم‌به‌قدم گسترش دهید. مهم‌ترین اصل این است که ابتدا یک سناریوی کوچک را کامل کنید، سپس سراغ پایگاه داده، دکمه‌ها، زمان‌بندی و استقرار دائمی بروید.

چطور با پایتون یک ربات تلگرام بسازیم؟ راهنمای کامل از نصب تا اجرا