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

ساخت ربات تلگرام با پایتون، سریع‌ترین و انعطاف‌پذیرترین روش برای اتوماتیک‌سازی پاسخ‌گویی به کاربران، اتصال سیستم‌های فروشگاهی و دریافت اعلان‌های لحظه‌ای است. در این مقاله عملی، ابتدا ساختار معماری اسنکرون (Async) در نسخه‌های جدید کتابخانه python-telegram-bot را بررسی می‌کنیم و سپس یک ربات پیشرفته با قابلیت منوهای شیشه‌ای، مدیریت فرم‌های چندمرحله‌ای و اتصال به سرور پیاده‌سازی خواهیم کرد.

فهرست مطالب

• ۱. دریافت توکن و آماده‌سازی محیط توسعه
• ۲. مقایسه روش‌های Long Polling و Webhook
• ۳. کدنویسی اولین ربات پایتون (نسخه Async)
• ۴. پیاده‌سازی دکمه‌های شیشه‌ای (Inline Keyboards)
• ۵. مدیریت فرم‌های چندمرحله‌ای با ConversationHandler
• ۶. سناریوی کاربردی: اتصال ربات به وب‌سایت
• ۷. استقرار و اجرای ۲۴ ساعته روی سرور (Linux Systemd)
• ۸. پرسش‌های متداول
• ۹. عیب‌یابی سریع و رفع خطاهای رایج

۱. دریافت توکن و آماده‌سازی محیط توسعه

برای ساخت ربات تلگرام با پایتون، ابتدا باید ربات خود را در سرورهای تلگرام ثبت کرده و کلید دسترسی (API Token) دریافت کنید. این کار کاملاً رایگان است و از طریق ربات رسمی BotFather انجام می‌شود.

پاسخ سریع: توکن ربات تلگرام رشته‌ای از حروف و اعداد است که مانند کلمه عبور ربات عمل می‌کند. برای دریافت آن، در تلگرام به آیدی @BotFather پیام داده، دستور /newbot را ارسال کنید و مراحل نام‌گذاری را انجام دهید.

1. در تلگرام عبارت @BotFather را جستجو کرده و وارد گفتگو شوید.
2. دستور /newbot را بفرستید و یک نام عمومی برای ربات انتخاب کنید.
3. یک نام کاربری (Username) یکتا انتخاب کنید که حتماً به bot ختم شود (مثال: my_shop_bot).
4. توکن اختصاصی API را کپی کرده و در جایی امن نگه دارید.

حالا محیط توسعه پایتون را آماده کنید. پیشنهاد می‌شود حتماً از Virtual Environment استفاده کنید تا تداخل کتابخانه‌ها پیش نیاید:

python -m venv venv
# در لینوکس و مک:
source venv/bin/activate
# در ویندوز:
venvScriptsactivate

# نصب آخرین نسخه کتابخانه رسمی
pip install python-telegram-bot python-dotenv

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

۲. مقایسه روش‌های دریافت پیام: Long Polling در برابر Webhook

ربات‌ها به دو روش متلفت داده‌های جدید را از تلگرام دریافت می‌کنند: روش درخواست متناوب (Long Polling) و روش فراخوانی وب (Webhook). انتخاب روش درست، تاثیر مستقیمی بر سرعت، نحوه هاستینگ و مصرف منابع سرور شما دارد.

۳. کدنویسی اولین ربات پایتون (نسخه Async)

در نسخه ۲۰ به بعد کتابخانه python-telegram-bot تمام دستگیره‌ها (Handlers) و توابع به‌صورت `async/await` نوشته می‌شوند. این ساختار مانع از قفل شدن برنامه در پردازش‌های سنگین می‌شود.

ابتدا یک فایل به نام .env ایجاد کنید و توکن خود را در آن ذخیره کنید:

BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyZ

سپس اسکریپت اصلی bot.py را به‌صورت زیر بنویسید:

import os
import logging
from dotenv import load_dotenv
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, filters, ContextTypes

# بارگذاری متغیرهای محیطی
load_dotenv()
TOKEN = os.getenv("BOT_TOKEN")

# تنظیمات مربوط به لاگ‌ها
logging.basicConfig(
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    level=logging.INFO
)

async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """پاسخ به دستور /start"""
    user_name = update.effective_user.first_name
    welcome_text = f"سلام {user_name} عزیز! به ربات پشتیبانی خوش آمدید.nچگونه می‌توانم کمکتان کنم؟"
    await update.message.reply_text(welcome_text)

async def handle_text(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """پاسخ متناسب به پیام‌های متنی عادی"""
    text_received = update.message.text
    await update.message.reply_text(f"شما گفتید: {text_received}")

if __name__ == '__main__':
    # ساخت اپلیکیشن
    app = ApplicationBuilder().token(TOKEN).build()

    # ثبت دستورات
    app.add_handler(CommandHandler("start", start_command))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_text))

    print("ربات فعال شد...")
    app.run_polling()

۴. پیاده‌سازی دکمه‌های شیشه‌ای (Inline Keyboards)

دکمه‌های شیشه‌ای چسبیده به پیام، حرفه‌ای‌ترین راه برای ارائه گزینه‌ها به کاربر هستند. با کلیک بر روی این دکمه‌ها، یک `callback_data` به سرور فرستاده می‌شود بدون اینکه چت شلوغ شود.

پاسخ سریع: برای ساخت دکمه شیشه‌ای از آرایه‌ای دو بعدی از کلاس InlineKeyboardButton استفاده می‌شود که در قالب InlineKeyboardMarkup به متد ارسال پیام کلاسی اضافه خواهد شد.

from telegram import InlineKeyboardButton, InlineKeyboardMarkup

async def show_menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = [
        [
            InlineKeyboardButton("کاتالوگ محصولات", callback_data="products"),
            InlineKeyboardButton("پشتیبانی", callback_data="support")
        ],
        [
            InlineKeyboardButton("مشاهده وب‌سایت", url="https://fa-tools.ir")
        ]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text("لطفاً یک گزینه را انتخاب کنید:", reply_markup=reply_markup)

async def button_click_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.callback_query
    await query.answer() # جهت حذف حالت در حال بارگذاری روی دکمه

    if query.data == "products":
        await query.edit_message_text(text="لیست محصولات خدمت شما...")
    elif query.data == "support":
        await query.edit_message_text(text="برای تماس با پشتیبانی پیام بگذارید.")

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

۵. مدیریت فرم‌های چندمرحله‌ای با ConversationHandler

وقتی نیاز است از کاربر چند اطلاعات متوالی دریافت کنید (مثلاً نام، شماره تلفن و آدرس برای ثبت سفارش)، از ماشین وضعیت یا همان ConversationHandler استفاده می‌کنید.

from telegram.ext import ConversationHandler

# تعریف مراحل
NAME, PHONE = range(2)

async def start_register(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("لطفاً نام و نام خانوادگی خود را وارد کنید:")
    return NAME

async def get_name(update: Update, context: ContextTypes.DEFAULT_TYPE):
    context.user_data['name'] = update.message.text
    await update.message.reply_text("عالی شد! حالا شماره تماس خود را بفرستید:")
    return PHONE

async def get_phone(update: Update, context: ContextTypes.DEFAULT_TYPE):
    context.user_data['phone'] = update.message.text
    name = context.user_data['name']
    phone = context.user_data['phone']
    
    await update.message.reply_text(f"اطلاعات ثبت شد:nنام: {name}nتلفن: {phone}")
    return ConversationHandler.END

async def cancel(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("عملیات لغو شد.")
    return ConversationHandler.END

# تعریف هندلر در بخش اصلی کد
conv_handler = ConversationHandler(
    entry_points=[CommandHandler('register', start_register)],
    states={
        NAME: [MessageHandler(filters.TEXT & ~filters.COMMAND, get_name)],
        PHONE: [MessageHandler(filters.TEXT & ~filters.COMMAND, get_phone)],
    },
    fallbacks=[CommandHandler('cancel', cancel)]
)

۶. سناریوی کاربردی: اتصال ربات به وب‌سایت و سیستم فروشگاهی

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

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

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

۷. استقرار و اجرای ۲۴ ساعته روی سرور (Linux Systemd)

برای اینکه ربات شما به‌صورت دائمی و بدون قطع شدن کار کند، باید آن را روی یک سرور مجازی (VPS) اجرا کرده و یک سرویس در لینوکس بسازید تا در صورت کرش کردن یا ریستارت سرور، ربات به‌طور خودکار مجدداً بیدار شود.

پاسخ سریع: بهترین روش در سرورهای اوبونتو/دبیان، تعریف فایل systemd است که فرایند پایتون را مدیریت کرده و در صورت خرابی برنامه‌، آن را در چند ثانیه ریسپاون (Respawn) می‌کند.

1. کدهای ربات را روی سرور آپلود کنید (مثلاً در مسیر /var/www/mybot).
2. یک فایل سرویس جدید در سیستم‌عامل بسازید:

   sudo nano /etc/systemd/system/mybot.service

3. محتوای زیر را داخل فایل قرار داده و ذخیره کنید:

[Unit]
Description=Telegram Bot Python Service
After=network.target

[Service]
User=root
WorkingDirectory=/var/www/mybot
ExecStart=/var/www/mybot/venv/bin/python /var/www/mybot/bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

دستورات زیر را برای فعال‌سازی و اجرای سرویس وارد کنید:

sudo systemctl daemon-reload
sudo systemctl enable mybot
sudo systemctl start mybot
# برای بررسی وضعیت سرویس:
sudo systemctl status mybot

۸. پرسش‌های متداول

۹. عیب‌یابی سریع و رفع خطاهای رایج

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

• خطای Conflict: terminated by other long poll:
  
  این خطا زمانی رخ می‌دهد که توکن ربات شما هم‌زمان در دو جا (مثلا روی سیستم شخصی و سرور) در حال اجرای run_polling باشد. اجرای قبلی را حتما متوقف کنید.
• خطای Unauthorized / Invalid Token:
  
  توکن وارد شده اشتباه است یا آن را در BotFather ریست کرده‌اید. فایل .env را چک کرده و فاصله‌های اضافی (Space) را پاک کنید.
• خطای Timed Out / NetworkError:
  
  دسترسی سیستم شما به سرورهای تلگرام مسدود است. اگر روی کامپیوتر شخصی هستید باید ابزار تغییر آی‌پی استفاده کنید و اگر روی سرور لینوکس هستید، مطمئن شوید سرور خارجی است.
• خطای BadRequest: Message is not modified:
  
  زمانی رخ می‌دهد که سعی دارید یک پیام را با محتوایی کاملاً یکسان مجدداً edit_text کنید. قبل از ویرایش، تغییر متون را چک کنید.