آموزش صفر تا صد ساخت ربات تلگرام با پایتون (سورس کد + رفع ارورهای رایگان)

اگر کلمه “ساخت ربات تلگرام” را جستجو کرده‌اید، احتمالاً ایده‌ای در سر دارید؛ شاید می‌خواهید یک ربات مدیریت گروه بسازید، یا یک فروشگاه خودکار، و یا شاید فقط می‌خواهید با کدنویسی سرگرم شوید. در هر صورت، جای درستی آمده‌اید.

در این مقاله، ما نه تنها روش قدیمی، بلکه جدیدترین متد سال ۲۰۲۶ را با استفاده از زبان قدرتمند پایتون بررسی می‌کنیم. همچنین به سوالات مهمی مثل “چطور ربات را ۲۴ ساعته روشن نگه داریم؟” و “چطور ارورهای رایج کتابخانه‌ها را رفع کنیم؟” پاسخ می‌دهیم.

چرا پایتون بهترین زبان برای طراحی ربات است؟

قبل از اینکه دست به کد شویم، باید بدانید که چرا بین این همه زبان، پایتون (Python) را انتخاب کرده‌ایم. پایتون به دلیل سادگی سینتکس (دستورات)، داشتن کتابخانه‌های قدرتمند و سرعت بالا در توسعه، محبوب‌ترین زبان برای ساخت ربات تلگرام است.

قبل از شروع، اگر هنوز با زبان پایتون آشنایی ندارید، پیشنهاد می‌کنیم حتماً نگاهی به [صفحه آموزش پایتون از مقدماتی تا پیشرفته] بیندازید تا مفاهیم پایه را سریع یاد بگیرید.

قدم اول: ابزارهای مورد نیاز برای ساخت ربات تلگرام (کامپیوتر یا گوشی؟)

یکی از جستجوهای پرتکرار شما در گوگل، “آموزش ساخت ربات تلگرام با گوشی” است. بگذارید همین اول تکلیف را روشن کنیم:

• آیا می‌شود با گوشی ربات ساخت؟ بله! با استفاده از اپلیکیشن‌هایی مثل Pydroid 3 می‌توانید کدهای پایتون را روی اندروید اجرا کنید.
• آیا پیشنهاد می‌شود؟ خیر. برای پروژه‌های جدی، دیباگ کردن و مدیریت فایل‌ها، شما به یک محیط کدنویسی حرفه‌ای روی کامپیوتر نیاز دارید.

پیشنهاد ما استفاده از ویرایشگر محبوب VS Code است. اگر آن را ندارید، مقاله [آموزش نصب وی اس کد] را مطالعه کنید و سپس برگردید.

پیش‌نیازهای ساخت ربات (قبل از شروع بخوانید)

برای اینکه در حین انجام مراحل به مشکل نخورید، این ۴ مورد را آماده کنید:

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

نصب بودن پایتون روی سیستم.

یک ویرایشگر متن (IDE) مثل VS Code یا PyCharm.

یک اکانت تلگرام فعال.

انتخاب بهترین کتابخانه برای ساخت ربات تلگرام

سوال مهم: “چه کتابخانه‌ای برای توسعه و ساخت ربات تلگرام مناسب است؟”

در پایتون دو رقیب اصلی وجود دارد:

1. Telebot (PyTelegramBotAPI): یادگیری آن بسیار آسان است اما برای پروژه‌های بزرگ و همزمان (Async) کمی محدودیت دارد.
2. Python-Telegram-Bot (PTB): این گزینه حرفه‌ای‌ترین انتخاب است. مستندات فوق‌العاده‌ای دارد، کاملاً از متد Async پشتیبانی می‌کند و شرکت‌های بزرگ از آن استفاده می‌کنند.

ما در این آموزش از python-telegram-bot (نسخه ۲۰ به بالا) استفاده می‌کنیم که سرعت و امنیت بیشتری دارد.

گام اول ساخت ربات تلگرام : دریافت توکن از BotFather (شناسنامه ربات)

برای اینکه کدهای پایتون شما بتوانند به سرورهای تلگرام فرمان دهند، نیاز به یک “کلید امنیتی” دارید. در تلگرام، تمام ربات‌ها توسط یک ربات اصلی به نام BotFather (پدرخوانده) ساخته و مدیریت می‌شوند.

برای دریافت این کلید (که به آن API Token می‌گوییم)، مراحل زیر را دقیق انجام دهید:

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

وارد تلگرام شوید و در کادر جستجو عبارت BotFather@ را تایپ کنید. دقت کنید که حتماً روی اکانتی کلیک کنید که تیک آبی دارد (اکانت‌های فیک زیادی با این نام وجود دارند). دکمه Start را بزنید تا لیست دستورات نمایش داده شود.

۲. ساخت ربات جدید

دستور زیر را تایپ کرده و ارسال کنید: /newbot بات‌فادر پاسخ می‌دهد: “خب، یک ربات جدید. اسمش را چه می‌گذارید؟”

۳. انتخاب “نام نمایشی” (Name)

این نامی است که در لیست چت‌ها و بالای صفحه ربات به کاربران نمایش داده می‌شود.

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

۴. انتخاب “نام کاربری” (Username) – مهم‌ترین بخش

حالا بات‌فادر از شما یک آیدی یا یوزرنیم می‌خواهد. این آیدی باید ۳ ویژگی داشته باشد:

1. یکتا باشد: یعنی قبلاً کسی آن را نگرفته باشد.
2. انگلیسی باشد: فقط حروف انگلیسی، اعداد و خط زیر (_).
3. با کلمه bot تمام شود: مثلاً TetrisBot یا Tetris_bot.

• مثال: Raya_Python_TestBot
• ⚠️ خطای رایج: اگر بات‌فادر گفت “Sorry, this username is already taken”، یعنی این آیدی قبلاً گرفته شده. باید انقدر تغییرش دهید تا قبول کند (مثلاً به آخرش عدد اضافه کنید).

۵. دریافت توکن (Token)

اگر نام کاربری تایید شود، بات‌فادر یک پیام طولانی تبریک می‌فرستد که شامل یک کد عجیب و غریب است (ترکیبی از اعداد و حروف).

این کد، همان توکن شماست. آن را کپی کنید.

• نمونه توکن: 78432432:AAFwgh5345345...

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

گام دوم ساخت ربات تلگرام : کدنویسی (سورس کد ساخت ربات تلگرام)

ما نمی‌خواهیم چرخ را از اول اختراع کنیم! برای ارتباط راحت با تلگرام، از قدرتمندترین کتابخانه پایتون استفاده می‌کنیم. ترمینال (CMD) خود را باز کنید و دستور زیر را بنویسید:

pip install python-telegram-bot

pip install python-telegram-bot

سورس کد ربات تلگرام با پایتون (متد Async)

این یک کد پایه و استاندارد است که پیام شما را اکو می‌کند (تکرار می‌کند):

ویرایشگر کد (VS Code) را باز کنید، یک فایل جدید به نام main.py بسازید و کدهای زیر را در آن کپی کنید.

توجه: در خط ۱۰، به جای عبارت TOKEN_SHOMA_INJA، توکنی که از بات‌فادر گرفتید را قرار دهید.

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

# 1. تابعی برای دستور استارت
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("سلام! من ربات جدید شما هستم.")

# 2. تابعی که پیام‌های متنی را جواب می‌دهد
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(f"شما گفتید: {update.message.text}")

if __name__ == '__main__':
    # توکن خود را اینجا بگذارید
    TOKEN = "TOKEN_SHOMA_INJA"
    
    # ساخت اپلیکیشن
    app = ApplicationBuilder().token(TOKEN).build()
    
    # اضافه کردن هندلرها
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & (~filters.COMMAND), echo))
    
    print("ربات روشن شد...")
    app.run_polling()

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

# 1. تابعی برای دستور استارت
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("سلام! من ربات جدید شما هستم.")

# 2. تابعی که پیام‌های متنی را جواب می‌دهد
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(f"شما گفتید: {update.message.text}")

if __name__ == '__main__':
    # توکن خود را اینجا بگذارید
    TOKEN = "TOKEN_SHOMA_INJA"
    
    # ساخت اپلیکیشن
    app = ApplicationBuilder().token(TOKEN).build()
    
    # اضافه کردن هندلرها
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & (~filters.COMMAND), echo))
    
    print("ربات روشن شد...")
    app.run_polling()

حل مشکلات و ارورهای رایج در ساخت ربات تلگرام (Troubleshooting)

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

رفع ارور: ImportError: cannot import name 'Filters' from 'telegram.ext'

دلیل ارور: این خطا زمانی رخ می‌دهد که شما از نسخه جدید کتابخانه (ورژن ۲۰+) استفاده می‌کنید، اما کدی که نوشته‌اید مربوط به نسخه‌های قدیمی (ورژن ۱۳ و پایین‌تر) است. در آپدیت‌های جدید، کلاس Filters (با F بزرگ) حذف شده و جای خود را به filters (با f کوچک) داده است.

راه حل:

1. به جای from telegram.ext import Filters، باید ایمپورت را حذف کنید.
2. به جای آن، filters را ایمپورت کنید (با حروف کوچک).
3. در کدنویسی به جای Filters.text باید بنویسید filters.TEXT.

(در سورس کدی که در بخش قبلی قرار دادیم، این مشکل حل شده و از متد جدید استفاده شده است).

سوال حیاتی: چگونه ربات را همیشه آنلاین نگه داریم؟

سوال شما: “چگونه کد ربات تلگرام را آنلاین کنم حتی اگه سیستم خاموش باشه؟”

وقتی شما کد را روی کامپیوتر خودتان (Localhost) اجرا می‌کنید، به محض اینکه سیستم را خاموش کنید یا اینترنت قطع شود، ربات هم خاموش می‌شود. برای اینکه ربات ۲۴ ساعته کار کند، باید کد را به یک “سرور” منتقل کنید.

برای این کار ۲ راه دارید:

1. استفاده از هاست ابری پایتون (Cloud Hosting): سرویس‌هایی مثل PythonAnywhere یا Heroku فضایی به شما می‌دهند که می‌توانید اسکریپت پایتون را آنجا آپلود کنید. (نسخه‌های رایگان محدودیتی دارند اما برای شروع عالی هستند).
2. خرید سرور مجازی (VPS): این روش حرفه‌ای‌تر است. شما یک کامپیوتر مجازی اجاره می‌کنید (لینوکس یا ویندوز) که در دیتاسنتر همیشه روشن است. فایل ربات را آنجا کپی می‌کنید و اجرا می‌کنید.