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

🗓 آخرین به‌روزرسانی: 28 مهر 1405

ساخت ربات تلگرام با پایتون یکی از جذاب‌ترین و پرطرفدارترین پروژه‌ها برای برنامه‌نویسان ایرانی است. با یک ربات می‌توانید به سؤالات تکراری مشتریان پاسخ دهید، سفارش بگیرید، فایل ارسال کنید، یادآوری بفرستید یا حتی یک بازی کوچک بسازید. خبر خوب این است که با پایتون و کتابخانه python-telegram-bot می‌توانید اولین ربات خود را در کمتر از یک ساعت بسازید.

در این آموزش قدم‌به‌قدم از ساخت ربات در BotFather شروع می‌کنیم، محیط پروژه را آماده می‌کنیم، کتابخانه را نصب می‌کنیم و رباتی می‌نویسیم که به دستور /start و /help پاسخ می‌دهد و پیام‌های کاربر را جواب می‌دهد. کدهای این آموزش با نسخه ۲۱ کتابخانه (ساختار async) نوشته شده‌اند.

پیش‌نیازهای این آموزش

• آشنایی با مفاهیم پایه پایتون مثل متغیرها، شرط‌ها و توابع.
• نصب پایتون ۳.۹ یا بالاتر روی سیستم (آموزش نصب پایتون در ویندوز).
• یک حساب تلگرام فعال.
• آشنایی با pip و محیط مجازی venv توصیه می‌شود.

ربات تلگرام چطور کار می‌کند؟

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

دو روش اصلی برای دریافت پیام‌ها وجود دارد:

• Polling: برنامه مرتب از تلگرام می‌پرسد «پیام جدیدی هست؟». این روش ساده است و برای یادگیری و ربات‌های کوچک عالی است. در این آموزش از همین روش استفاده می‌کنیم.
• Webhook: تلگرام هر پیام جدید را مستقیم به آدرس سرور شما می‌فرستد. این روش برای ربات‌های پربازدید مناسب‌تر است ولی به دامنه و SSL نیاز دارد.

قدم ۱: ساخت ربات در BotFather و دریافت توکن

BotFather ربات رسمی تلگرام برای ساخت و مدیریت ربات‌هاست. مراحل زیر را انجام دهید:

1. در تلگرام عبارت @BotFather را جستجو کنید و ربات دارای تیک آبی را باز کنید.
2. دستور /newbot را ارسال کنید.
3. یک نام نمایشی برای ربات وارد کنید؛ مثلاً «Dev Source Helper».
4. یک نام کاربری یکتا وارد کنید که حتماً به bot ختم شود؛ مثلاً devsource_helper_bot.
5. BotFather یک توکن طولانی شبیه 123456789:AA... به شما می‌دهد. این توکن کلید کنترل ربات است.

هشدار امنیتی: توکن را هرگز در گیت‌هاب، اسکرین‌شات یا کد عمومی منتشر نکنید. هر کس توکن را داشته باشد، کنترل کامل ربات شما را دارد. اگر توکن لو رفت، در BotFather با دستور /revoke آن را باطل کنید.

قدم ۲: ساخت پروژه و نصب کتابخانه

یک پوشه برای پروژه بسازید، محیط مجازی ایجاد کنید و کتابخانه را نصب کنید:

mkdir my_bot
cd my_bot
python -m venv venv

# Windows
venv\Scripts\activate
# Linux and macOS
source venv/bin/activate

pip install "python-telegram-bot==21.*"

برای اینکه توکن داخل کد نباشد، آن را در یک متغیر محیطی قرار می‌دهیم. در ویندوز (PowerShell):

$env:BOT_TOKEN="YOUR_TOKEN"

و در لینوکس یا مک:

export BOT_TOKEN="YOUR_TOKEN"

قدم ۳: اولین ربات؛ پاسخ به دستور /start

فایلی به نام bot.py بسازید و کد زیر را در آن بنویسید:

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

TOKEN = os.environ["BOT_TOKEN"]


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    user = update.effective_user
    await update.message.reply_text(
        f"Hello {user.first_name}! 👋\nWelcome to the Dev Source bot."
    )


def main() -> None:
    app = Application.builder().token(TOKEN).build()
    app.add_handler(CommandHandler("start", start))
    print("Bot is running...")
    app.run_polling()


if __name__ == "__main__":
    main()

حالا برنامه را اجرا کنید:

python bot.py

به ربات خود در تلگرام بروید و /start را بفرستید. ربات با نام شما سلام می‌کند. تبریک! اولین ربات تلگرام خود را با پایتون ساختید.

توضیح خط‌به‌خط کد

• Application.builder().token(TOKEN).build(): شیء اصلی ربات را با توکن می‌سازد.
• async def start(...): یک تابع ناهمگام (async) است. نسخه ۲۰ به بعد کتابخانه کاملاً بر پایه asyncio است؛ به همین دلیل توابع پاسخ‌دهنده با async def تعریف می‌شوند و برای ارسال پیام از await استفاده می‌کنیم.
• update: اطلاعات پیام دریافتی، کاربر و چت را در خود دارد.
• context: ابزارهای کمکی مثل دسترسی به ربات، داده‌های کاربر و آرگومان‌های دستور را فراهم می‌کند.
• CommandHandler("start", start): می‌گوید هر وقت کاربر /start فرستاد، تابع start اجرا شود.
• run_polling(): ربات را روشن نگه می‌دارد و مدام پیام‌های جدید را دریافت می‌کند. برای توقف، Ctrl+C را بزنید.

قدم ۴: افزودن دستور /help و پاسخ به پیام‌های متنی

یک ربات واقعی باید به پیام‌های معمولی هم پاسخ دهد. برای این کار از MessageHandler و فیلترها استفاده می‌کنیم. کد کامل‌تر زیر را جایگزین کنید:

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

TOKEN = os.environ["BOT_TOKEN"]

ANSWERS = {
    "hello": "Hello! How can I help you?",
    "python": "Free Python course: https://dev-source.ir/python-course/",
    "wordpress": "WordPress tutorials: https://dev-source.ir/category/wordpress-tutorials/",
}


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(
        f"Hello {update.effective_user.first_name}! Send /help to see the commands."
    )


async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(
        "Commands:\n/start - start the bot\n/help - show this help\n\n"
        "Send the word python or wordpress to get a tutorial link."
    )


async def reply(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    text = update.message.text.strip()
    for keyword, answer in ANSWERS.items():
        if keyword in text.lower():
            await update.message.reply_text(answer)
            return
    await update.message.reply_text(f"Got your message: {text}")


def main() -> None:
    app = Application.builder().token(TOKEN).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("help", help_command))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, reply))
    app.run_polling()


if __name__ == "__main__":
    main()

در این نسخه:

• یک دیکشنری به نام ANSWERS داریم که کلیدواژه‌ها و پاسخ‌ها را نگه می‌دارد.
• filters.TEXT & ~filters.COMMAND یعنی فقط پیام‌های متنی که دستور نیستند به تابع reply برسند.
• تابع reply با یک حلقه بررسی می‌کند کدام کلیدواژه در پیام وجود دارد و اگر هیچ‌کدام نبود، خود پیام را برمی‌گرداند.

قدم ۵: دریافت آرگومان از دستور

گاهی کاربر بعد از دستور اطلاعاتی می‌فرستد؛ مثلاً /square 7. این اطلاعات در context.args به‌صورت لیست قرار می‌گیرد:

async def square(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if not context.args or not context.args[0].lstrip("-").isdigit():
        await update.message.reply_text("Usage: /square 7")
        return
    n = int(context.args[0])
    await update.message.reply_text(f"The square of {n} is {n * n}")

# inside main():
# app.add_handler(CommandHandler("square", square))

در اینجا با متد isdigit() که در درس متدهای رشته یاد گرفتیم، ورودی را اعتبارسنجی کردیم تا ربات با ورودی اشتباه خطا ندهد.

قدم ۶: تنظیم منوی دستورها در BotFather

برای اینکه کاربر هنگام تایپ / فهرست دستورها را ببیند، در BotFather دستور /setcommands را بفرستید، ربات را انتخاب کنید و متن زیر را ارسال کنید:

start - Start the bot
help - Show the commands
square - Square a number

همچنین با /setdescription و /setuserpic می‌توانید توضیح و عکس پروفایل ربات را تنظیم کنید.

مشکلات رایج و راه‌حل

• KeyError: ‘BOT_TOKEN’: متغیر محیطی را در همان ترمینالی که برنامه را اجرا می‌کنید تنظیم نکرده‌اید.
• ربات جواب نمی‌دهد: مطمئن شوید برنامه در حال اجراست و فقط یک نسخه از آن روشن است. اجرای هم‌زمان دو نسخه با یک توکن خطای Conflict می‌دهد.
• خطای اتصال یا Timeout: در صورت محدودیت دسترسی شبکه به API تلگرام، ربات را روی یک سرور خارج از محدودیت اجرا کنید؛ در درس‌های بعدی اجرای ۲۴ ساعته روی سرور را آموزش می‌دهیم.
• کدهای قدیمی اینترنت کار نمی‌کنند: بسیاری از آموزش‌ها با نسخه ۱۳ کتابخانه (Updater و Dispatcher) نوشته شده‌اند. از نسخه ۲۰ ساختار به Application و async تغییر کرده است.

یک ایده ساده و کاربردی، دستور /weather است که وضعیت هوای یک شهر را برمی‌گرداند. منطق گرفتن و پردازش داده هوا را در ساخت برنامه هواشناسی با پایتون و API رایگان کامل و بدون نیاز به کلید API نوشته‌ایم و می‌توانید آن را مستقیم در ربات خود استفاده کنید.

ایده‌هایی برای توسعه ربات

• ربات پاسخ‌گوی سؤالات متداول یک کسب‌وکار
• ربات یادآور کارها با الهام از پروژه لیست کارها با پایتون
• ربات آزمون چهارگزینه‌ای مشابه پروژه آزمون با پایتون
• ربات فروشگاهی با کاتالوگ محصول و ثبت سفارش

📌 همچنین بخوانید: بازار کار پایتون در ایران، دانلود ویدیو از یوتیوب با پایتون و yt-dlp و رسم نمودار در پایتون با Matplotlib

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

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

بله. ساخت ربات در BotFather، کتابخانه python-telegram-bot و خود پایتون همگی رایگان هستند. فقط برای روشن ماندن ۲۴ ساعته ربات به یک سرور یا هاست نیاز دارید.

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

python-telegram-bot محبوب‌ترین و مستندترین گزینه است. aiogram و pyTelegramBotAPI (telebot) هم گزینه‌های رایجی هستند. برای شروع، python-telegram-bot به دلیل مستندات کامل پیشنهاد می‌شود.

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

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

توکن ربات لو رفته است؛ چه کار کنم؟

در BotFather دستور /revoke را بزنید و ربات را انتخاب کنید تا توکن قبلی باطل شود و توکن جدید بگیرید. توکن را در متغیر محیطی یا فایل .env نگه دارید و هرگز آن را در گیت‌هاب یا اسکرین‌شات منتشر نکنید.

چرا ربات من به پیام‌ها جواب نمی‌دهد؟

اول مطمئن شوید اسکریپت در حال اجراست و خطایی در ترمینال چاپ نشده است. سپس درستی توکن و ثبت شدن هندلرها قبل از run_polling() را بررسی کنید. اگر کد را روی سیستمی اجرا می‌کنید که به API تلگرام دسترسی ندارد، ربات پیام‌ها را دریافت نمی‌کند؛ در این حالت آن را روی یک سرور با دسترسی آزاد اجرا کنید.

جمع‌بندی

در این آموزش یاد گرفتیم چطور در BotFather ربات بسازیم، توکن را امن نگه داریم، کتابخانه python-telegram-bot نسخه ۲۱ را نصب کنیم و رباتی بنویسیم که به دستورهای /start، /help و /square و پیام‌های متنی پاسخ دهد. همچنین با مفهوم Polling، توابع async و Handlerها آشنا شدیم. در درس بعدی دکمه‌های شیشه‌ای (Inline Keyboard) را به ربات اضافه می‌کنیم.

پیش‌نیاز پیشنهادی: نصب کتابخانه با pip و ساخت محیط مجازی venv

مشاهده دوره رایگان پایتون سطح متوسط