آموزش ساخت ربات تلگرام با پایتون از صفر

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

چرا اصلا ربات تلگرام بسازیم؟

شاید این سوال برات پیش اومده باشه که تو این همه اپلیکیشن و پلتفرم، چرا باید وقت بذاریم و ربات تلگرام بسازیم؟ خب، دلایل زیادی وجود داره که تلگرام رو به یک پلتفرم فوق‌العاده برای ربات‌سازی تبدیل می‌کنه:

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

آماده‌سازی محیط برانمه‌نویسی (پیش‌نیازها)

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

نصب پایتون

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

1. به سایت رسمی پایتون (python.org) برو.
2. نسخه مربوط به سیستم‌عاملت (ویندوز، مک، لینوکس) رو دانلود کن.
3. فایل نصبی رو اجرا کن. حواست باشه تیک “Add Python to PATH” رو بزنی تا بعدا از طریق ترمینال یا CMD راحت‌تر باشی.

برای اینکه مطمئن بشی پایتون درست نصب شده، ترمینال (یا CMD در ویندوز) رو باز کن و این دستور رو بزن:

    
        python --version
        # یا
        python3 --version
    

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

نصب کتابخانه `python-telegram-bot`

پایتون به تنهایی نمی‌تونه با API تلگرام صحبت کنه. برای همین، به یک کتابخانه کمکی نیاز داریم که کارمون رو خیلی راحت‌تر می‌کنه. بهترین و پرطرفدارترین کتابخونه برای این کار، python-telegram-bot هست.

توی همون ترمینالی که باز کردی، این دستور رو بزن:

    
        pip install python-telegram-bot
    

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

ساخت ربات در تلگرام و گرفتن توکن

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

1. تلگرام رو باز کن: وارد اپلیکیشن تلگرام شو، چه روی گوشی و چه روی دسکتاپ.
2. دنبال @BotFather بگرد: توی قسمت جستجو، عبارت @BotFather رو سرچ کن و وارد چت با این ربات رسمی تلگرام شو.
3. دستور /newbot رو ارسال کن: به BotFather پیام /newbot رو بفرست.
4. یک نام برای رباتت انتخاب کن: BotFather ازت می‌خواد یه اسم برای رباتت انتخاب کنی. این اسمیه که برای کاربرا نمایش داده میشه، مثلا: ربات تست من.
5. یک نام کاربری (Username) انتخاب کن: حالا باید یه نام کاربری یکتا برای رباتت انتخاب کنی. این نام کاربری باید به bot ختم بشه، مثلا: MyTestRobot_bot.
6. توکن رو دریافت کن: اگه همه چی درست پیش رفته باشه، BotFather یه پیام برات می‌فرسته که حاوی توکن (API Token) رباتته. یه رشته طولانی از حروف و اعداد. این توکن رو جایی امن کپی کن.

اولین ربات پایتونی ما: سلام دنیا!

حالا که توکن رو داریم، می‌تونیم اولین کد رباتمون رو بنویسیم. این ربات خیلی ساده‌ست و فقط وقتی کاربر دستور /start رو بهش میده، یه پیام خوش‌آمدگویی می‌فرسته.

نوشتن کد پایه

یک فایل جدید با نام bot.py ایجاد کن و کد زیر رو توش کپی کن:

    
        from telegram.ext import Updater, CommandHandler

        # تابعی برای پاسخ به دستور /start
        def start(update, context):
            """وقتی کاربر دستور /start رو ارسال می‌کنه."""
            user = update.effective_user
            context.bot.send_message(
                chat_id=update.effective_chat.id,
                text=f"سلام {user.first_name}! چطوری رفیق؟ من ربات تو هستم."
            )

        def main():
            """نقطه ورود اصلی برای راه‌اندازی ربات."""
            # توکن رباتت رو اینجا بذار (همونی که از BotFather گرفتی)
            # پیشنهاد میشه توکن رو از طریق متغیرهای محیطی یا فایل config بخونی
            TOKEN = "YOUR_BOT_TOKEN_HERE" 

            updater = Updater(TOKEN, use_context=True) # Updater پیام‌های جدید رو از تلگرام می‌گیره

            dispatcher = updater.dispatcher # Dispatcher پیام‌ها رو به توابع مناسب هدایت می‌کنه

            # اضافه کردن هندلر برای دستور /start
            dispatcher.add_handler(CommandHandler("start", start))

            # شروع دریافت پیام‌ها (polling)
            updater.start_polling()

            # منتظر می‌مونه تا ربات با Ctrl+C متوقف بشه
            updater.idle()

        if __name__ == '__main__':
            main()
    

اجرای ربات

حالا که کد رو نوشتی، باید ربات رو اجرا کنی. توکن YOUR_BOT_TOKEN_HERE رو با توکن واقعی رباتت که از BotFather گرفتی جایگزین کن. بعد ترمینال رو باز کن، به پوشه‌ای که فایل bot.py رو ذخیره کردی برو و دستور زیر رو اجرا کن:

    
        python bot.py
        # یا
        python3 bot.py
    

اگه همه چی درست باشه، رباتت شروع به کار می‌کنه. حالا به تلگرام برو، رباتت رو پیدا کن (با سرچ کردن نام کاربریش) و دستور /start رو براش بفرست. باید ببینی که ربات بهت پیام خوش‌آمدگویی میده!

اضافه کردن قابلیت‌های بیشتر: پاسخ به پیام‌ها

ربات “سلام دنیا” خوبه، ولی خیلی هیجان‌انگیز نیست. بیا قابلیت‌های بیشتری بهش اضافه کنیم.

پاسخ متنی ساده

می‌خوایم رباتمون به هر پیام متنی که دریافت می‌کنه، یه جواب مشخص بده.

    
        from telegram.ext import Updater, CommandHandler, MessageHandler, filters

        # ... (کد تابع start و main که قبلا نوشتیم) ...

        # تابعی برای پاسخ به پیام‌های متنی
        def echo(update, context):
            """وقتی کاربر پیامی ارسال می‌کنه."""
            text = update.message.text
            context.bot.send_message(chat_id=update.effective_chat.id, text=f"تو گفتی: {text}")

        def main():
            TOKEN = "YOUR_BOT_TOKEN_HERE" 
            updater = Updater(TOKEN, use_context=True)
            dispatcher = updater.dispatcher

            dispatcher.add_handler(CommandHandler("start", start))
            
            # اضافه کردن هندلر برای پیام‌های متنی (غیر از دستورات)
            dispatcher.add_handler(MessageHandler(filters.TEXT & (~filters.COMMAND), echo))

            updater.start_polling()
            updater.idle()

        # ... (توابع start و main کامل اینجا قرار می‌گیرن) ...
    

اینجا از MessageHandler و filters.TEXT استفاده کردیم تا هر پیام متنی رو شناسایی کنیم. (~filters.COMMAND) هم یعنی اگه پیام، خودش یه دستور (مثل /start) بود، این هندلر فعال نشه. حالا ربات رو دوباره اجرا کن و هر متنی بنویسی، بهت جواب میده.

دستورات سفارشی

می‌تونی دستورات خودت رو هم به ربات اضافه کنی، مثلاً یه دستور /help:

    
        # ... (سایر ایمپورت‌ها و توابع) ...

        def help_command(update, context):
            """وقتی کاربر دستور /help رو ارسال می‌کنه."""
            help_text = "سلام رفیق! من یه ربات ساده‌ام. n" 
                        "اینا دستوراتیه که می‌فهمم:n" 
                        "/start - شروع ربات و خوش‌آمدگوییn" 
                        "/help - نمایش این پیام راهنماn" 
                        "هر متن دیگه‌ای بفرستی، همون رو بهت برمی‌گردونم."
            context.bot.send_message(chat_id=update.effective_chat.id, text=help_text)

        def main():
            TOKEN = "YOUR_BOT_TOKEN_HERE" 
            updater = Updater(TOKEN, use_context=True)
            dispatcher = updater.dispatcher

            dispatcher.add_handler(CommandHandler("start", start))
            dispatcher.add_handler(CommandHandler("help", help_command)) # اضافه کردن هندلر جدید
            dispatcher.add_handler(MessageHandler(filters.TEXT & (~filters.COMMAND), echo))

            updater.start_polling()
            updater.idle()

        # ...
    

ربات رو دوباره اجرا کن و /help رو بفرست تا جادوش رو ببینی!

مدیریت وضعیت و داده‌ها (Persistent Data)

برای اینکه رباتت بتونه کارهای پیچیده‌تر انجام بده، مثلاً یه بازی ساده، یا جمع‌آوری اطلاعات از کاربر در چند مرحله، نیاز به “مدیریت وضعیت” داری. یعنی ربات باید بدونه در هر لحظه کاربر در چه مرحله‌ای از تعامل با رباته.

کتابخانه python-telegram-bot برای این کار مکانیزم‌های قدرتمندی مثل ConversationHandler رو داره. ConversationHandler بهت اجازه میده یه “گفتگو” چند مرحله‌ای با کاربر داشته باشی و حالت‌های مختلف اون رو مدیریت کنی.

اگه می‌خوای اطلاعاتت رو به صورت دائمی ذخیره کنی (که با هر بار خاموش و روشن شدن ربات از بین نره)، باید از یه دیتابیس (مثل SQLite که خیلی ساده‌ست و نیازی به سرور نداره، یا PostgreSQL برای پروژه‌های بزرگ‌تر) استفاده کنی. یا حتی می‌تونی اطلاعات رو توی فایل‌های JSON ذخیره کنی.

کار با دکمه‌های شیشه‌ای (Inline Keyboards)

یکی از جذاب‌ترین ویژگی‌های ربات‌های تلگرام، دکمه‌های شیشه‌ای (Inline Keyboards) هستن. این دکمه‌ها زیر پیام‌های ربات ظاهر میشن و با کلیک کردن روی اونها، می‌تونی کارهای مختلفی انجام بدی، بدون اینکه پیام جدیدی توی چت ارسال بشه.

ساخت دکمه‌ها

برای ساخت دکمه‌ها از InlineKeyboardButton و InlineKeyboardMarkup استفاده می‌کنیم:

    
        from telegram import InlineKeyboardButton, InlineKeyboardMarkup
        from telegram.ext import Updater, CommandHandler, CallbackQueryHandler # CallbackQueryHandler برای کلیک دکمه‌ها

        def show_buttons(update, context):
            """دستور /buttons رو ارسال کن تا دکمه‌ها رو ببینی."""
            keyboard = [
                [
                    InlineKeyboardButton("گزینه ۱", callback_data='option_1'),
                    InlineKeyboardButton("گزینه ۲", callback_data='option_2')
                ],
                [InlineKeyboardButton("برو به سایت", url='https://fa-tools.ir/')]
            ]
            reply_markup = InlineKeyboardMarkup(keyboard)
            context.bot.send_message(chat_id=update.effective_chat.id, 
                                     text="یکی از گزینه‌ها رو انتخاب کن:", 
                                     reply_markup=reply_markup)

        # تابع main رو آپدیت کن
        def main():
            TOKEN = "YOUR_BOT_TOKEN_HERE" 
            updater = Updater(TOKEN, use_context=True)
            dispatcher = updater.dispatcher

            dispatcher.add_handler(CommandHandler("start", start))
            dispatcher.add_handler(CommandHandler("help", help_command))
            dispatcher.add_handler(CommandHandler("buttons", show_buttons)) # اضافه کردن هندلر جدید برای دکمه‌ها
            dispatcher.add_handler(MessageHandler(filters.TEXT & (~filters.COMMAND), echo))

            # ... (بقیه کد) ...
    

توی این مثال، دکمه اول و دوم callback_data دارن که بعداً به ما کمک می‌کنه بفهمیم کدوم دکمه کلیک شده. دکمه سوم هم کاربر رو به یه آدرس مشخص می‌فرسته.

پاسخ به کلیک‌ها (CallbackQueryHandler)

حالا باید یه هندلر داشته باشیم که وقتی روی دکمه‌ها کلیک شد، عکس‌العمل نشون بده:

    
        # ... (ایمپورت‌ها) ...

        def button_callback_handler(update, context):
            """وقتی روی دکمه‌های شیشه‌ای کلیک میشه."""
            query = update.callback_query
            query.answer() # ضروریه که به CallbackQuery پاسخ بدیم

            if query.data == 'option_1':
                query.edit_message_text(text="شما گزینه ۱ را انتخاب کردید.")
            elif query.data == 'option_2':
                query.edit_message_text(text="شما گزینه ۲ را انتخاب کردید.")
            else:
                query.edit_message_text(text="گزینه نامشخص.")

        # تابع main رو آپدیت کن و این خط رو به dispatcher اضافه کن:
        def main():
            # ...
            dispatcher.add_handler(CallbackQueryHandler(button_callback_handler))
            # ...
    

query.answer() خیلی مهمه، چون به تلگرام میگه که ما کلیک رو دریافت کردیم و دیگه اون حالت “در حال بارگذاری” از روی دکمه میره. edit_message_text هم اجازه میده بدون ارسال پیام جدید، همون پیام قبلی رو ویرایش کنیم.

استقرار ربات (Deployment)

تا اینجا رباتمون فقط وقتی فایل bot.py رو اجرا می‌کنیم، کار می‌کنه و وقتی برنامه رو می‌بندیم، آفلاین میشه. برای اینکه رباتت همیشه آنلاین باشه و به پیام‌ها پاسخ بده، باید اون رو روی یک سرور یا سرویس هاستینگ “استقرار” (Deploy) بدی.

گزینه‌های استقرار

• Heroku: یک پلتفرم PaaS (Platform as a Service) رایگان (با محدودیت) و محبوب برای استقرار اپلیکیشن‌های پایتون. تنظیماتش نسبتاً ساده‌ست.
• PythonAnywhere: یه گزینه عالی برای پروژه‌های کوچک پایتون، مخصوصاً اگه تازه کار هستی. محیط وب و کنسول آنلاین داره.
• VPS (Virtual Private Server): اگه کنترل کامل روی سرور نیاز داری و پروژهت بزرگتره، می‌تونی یه VPS (مثلاً از DigitalOcean, Vultr) بگیری و خودت ربات رو روش بالا بیاری.
• Docker و Kubernetes: برای پروژه‌های بزرگ و مقیاس‌پذیر، می‌تونی از داکر برای کپسوله‌سازی رباتت و از Kubernetes برای مدیریت کانتینرها استفاده کنی.

نکات مهم در استقرار

• متغیرهای محیطی: هرگز توکن رباتت رو مستقیم توی کد نذار. همیشه از os.environ.get("BOT_TOKEN") استفاده کن و توکن رو در متغیرهای محیطی سرورت تعریف کن. این یه بحث امنیتی مهم توی کدهای آماده خیلی بهش اشاره شده.
• Webhook یا Polling: برای استقرار، معمولاً از Webhook استفاده میشه که تلگرام پیام‌ها رو به یک URL مشخص روی سرور تو می‌فرسته. این روش کارآمدتره. Polling (که الان ازش استفاده کردی) برای توسعه محلی خوبه ولی برای سرور، مصرف منابعش بالاست.
• مانیتورینگ و لاگینگ: مطمئن شو که رباتت لاگ‌ها رو ثبت می‌کنه تا اگه مشکلی پیش اومد، بتونی راحت پیداش کنی.

جدول راهنمای دستورات پایه ربات تلگرام

این جدول یه خلاصه از دستورات مهمی هست که ممکنه تو ربات تلگرامت استفاده کنی:

عیب‌یابی سریع (Troubleshooting)

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

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

سوالات متداول (FAQ)

رفیق برنامه‌نویس، تبریک می‌گم! تو حالا اصول اولیه ساخت ربات تلگرام با پایتون رو یاد گرفتی و یه قدم بزرگ تو دنیای اتوماسیون برداشتی. این تازه شروع کاره. پایتون و API تلگرام پر از قابلیت‌های هیجان‌انگیز دیگه هستن که می‌تونی کشف کنی و باهاشون پروژه‌های بی‌نظیری بسازی. ادامه بده و از کدنویسی لذت ببر! اگه سوالی داشتی یا خواستی کدهای آماده جاوااسکریپت، HTML، یا حتی پایتون رو پیدا کنی، حتماً یه سری به fa-tools.ir/snippets/ بزن.