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

ربات‌های تلگرامی در زمان حاضره فراتر از یک ابزار سرگرمی هستند؛ آن‌ها به دستیاران هوشمند، فروش‌رسانیگاه‌های آنلاین، پلتفرم‌های پشتیبانی مشتریان و ابزارهای مدیریت جوامع تبدیل شده‌اند. استفاده از زبان برنامه‌نویسی پایتون (Python) به دلیل سینتکس ساده، کتابخانه‌های غنی و قدرت بالا، در کنار یک پایگاه داده رابطه‌ای و قدرتمند مانند MySQL برای ذخیره دائمی و ساختاریافته شرح، یکی از حرفه‌ای‌ترین ترکیب‌ها برای توسعه ربات‌های تلگرامی است.

در این مقاله، به صورت قدم‌به‌قدم، صفر تا صد ساخت یک ربات تلگرام را یاد می‌گیریم. نه تنها ربات را می‌سازیم، بلکه داده‌ها کاربران (مانند آیدی، نام و زمان عضویت) را در MySQL ذخیره کرده و به آن‌ها نمایش می‌دهیم. در انتها نیز به تمامی سوالات و چالش‌های احتمالی شما پاسخ خواهیم داد.

قبل از نوشتن اولین خط کد، باید بستر کار را فراهم کنیم. موارد زیر را روی سیستم خود آماده کنید:

برای ارتباط کدهای پایتون با سرورهای تلگرام، به یک کلید اختصاصی به نام API Token نیاز داریم. این توکن مانند رمز عبور ربات شماست.

برای ذخیره اطلاعات کاربرانی که ربات را استارت می‌زنند، باید یک پایگاه داده و جدول بسازیم. وارد محیط مدیریت MySQL خود (مثل phpMyAdmin در XAMPP یا خط فرمان MySQL) شوید و کدهای SQL زیر را اجرا کنید:

-- ۱. ساخت پایگاه داده تازه با پشتیبانی از زبان فارسی (Emoji و حروف فارسی)
CREATE DATABASE telegram_bot_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- ۲. انتخاب پایگاه داده برای اعمال دگرگونی‌ها
USE telegram_bot_db;

-- ۳. ساخت جدول برای ذخیره بیانات کاربران
CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,        -- شناسه ردیف (خودکار اضافه می‌شود)
    chat_id BIGINT UNIQUE NOT NULL,           -- آیدی عددی و یکتای کاربر در تلگرام
    username VARCHAR(255),                    -- یوزرنیم تلگرام کاربر (بدون @)
    first_name VARCHAR(255),                  -- نام کاربر
    join_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP -- تاریخ و زمان دقیق عضویت
);

با اجرای این کد، پایگاه داده telegram_bot_db و جدول users آماده ذخیره‌سازی داده‌ها می‌شوند.

برای اینکه پایتون بتواند هم با تلگرام و هم با دیتابیس صحبت کند، باید افزونه‌های (کتابخانه‌های) مربوطه را نصب کنیم. ترمینال (CMD یا PowerShell) خود را باز کرده و دستور زیر را اجرا کنید:

pip install python-telegram-bot mysql-coector-python

• python-telegram-bot: محبوب‌ترین و قدرتمندترین کتابخانه پایتون برای کار با API تلگرام (پشتیبانی مفصل از حالت Asynchronous).
• mysql-coector-python: رابط رسمی شرکت اوراکل برای اتصال پایتون به پایگاه داده MySQL.

قدم چهارم: برنامه‌نویسی ربات (کد دقیق با دو دستور)

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

توجه: مقادیر BOT_TOKEN و گزارش‌ها دیتابیس (user و password) را بر پایه سیستم خود تغییر دهید.

import mysql.coector
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

# ==========================================
# ۱. تنظیمات پایه‌ای ربات و دیتابیس
# ==========================================
BOT_TOKEN = "YOUR_BOT_TOKEN_HERE"  # توکن ربات خود را اینجا پیست کنید

DB_CONFIG = {
    'host': 'localhost',
    'user': 'root',            # معمولاً در XAMPP نام کاربری root است
    'password': '',            # اگر رمز نگذاشته‌اید، خالی بگذارید
    'database': 'telegram_bot_db'
}

# ==========================================
# ۲. تابع اتصال ایمن به دیتابیس
# ==========================================
def get_db_coection():
    try:
        co = mysql.coector.coect(**DB_CONFIG)
        return co
    except mysql.coector.Error as err:
        print(f"❌ Error coecting to database: {err}")
        return None

# ==========================================
# ۳. هندلر دستور /start (ثبت اطلاعات در دیتابیس)
# ==========================================
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user = update.effective_user
    chat_id = user.id
    username = user.username
    first_name = user.first_name

    co = get_db_coection()
    if co:
        cursor = co.cursor(dictionary=True)
        # مرور وجود کاربر در دیتابیس
        cursor.execute("SELECT * FROM users WHERE chat_id = %s", (chat_id,))
        existing_user = cursor.fetchone()

        if not existing_user:
            # کاربر تازه است: Insert در دیتابیس
            insert_query = "INSERT INTO users (chat_id, username, first_name) VALUES (%s, %s, %s)"
            cursor.execute(insert_query, (chat_id, username, first_name))
            co.commit()
            welcome_text = f"سلام {first_name} عزیز! خیلی خوش اومدی.n✅ داده‌ها شما با موفقیت در دیتابیس ما ثبت شد!برای دیدن پروفایل خود دستور /profile را ارسال کنید."
        else:
            # کاربر قدیمی است
            welcome_text = f"سلام مجدد {first_name} جان!n شما قبلاً در ربات ما ثبت‌نام کرده‌اید.برای دیدن پروفایل خود دستور /profile را ارسال کنید."
            
        cursor.close()
        co.close()
    else:
        welcome_text = "⚠ سلام! ربات فعال است اما ارتباط با دیتابیس برقرار نیست. لطفاً بعداً تلاش کنید."

    await update.message.reply_text(welcome_text)

# ==========================================
# ۴. هندلر دستور /profile (خواندن داده‌ها از دیتابیس)
# ==========================================
async def profile(update: Update, context: ContextTypes.DEFAULT_TYPE):
    chat_id = update.effective_user.id
    
    co = get_db_coection()
    if co:
        cursor = co.cursor(dictionary=True)
        cursor.execute("SELECT * FROM users WHERE chat_id = %s", (chat_id,))
        user_data = cursor.fetchone()
        
        if user_data:
            # فرمت کردن تاریخ عضویت
            join_date = user_data['join_date'].strftime("%Y-%m-%d %H:%M:%S")
            profile_text = (
                f" **پروفایل شما در ربات**"
                f"نام: {user_data['first_name']}n"
                f"نام کاربری: @{user_data['username'] if user_data['username'] else 'ندارد'}n"
                f"آیدی عددی: `{user_data['chat_id']}`n"
                f" تاریخ عضویت: {join_date}"
            )
        else:
            profile_text = "❌ گزارش‌ها شما در دیتابیس یافت نشد! لطفاً ابتدا /start را بزنید."
            
        cursor.close()
        co.close()
    else:
        profile_text = "⚠ خطای سرور پایگاه داده."

    # ارسال پیام با فرمت Markdown برای بولد شدن متن‌ها
    await update.message.reply_text(profile_text, parse_mode='Markdown')

# ==========================================
# ۵. اجرای اصلی ربات
# ==========================================
if __name__ == '__main__':
    print(" Bot is starting...")
    
    # ساخت اپلیکیشن و معرفی توکن
    app = ApplicationBuilder().token(BOT_TOKEN).build()

    # اتصال دستورات تلگرام به توابع پایتون
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("profile", profile))

    print("✅ Bot is ruing! Press Ctrl+C to stop.")
    
    # روشن نگه داشتن ربات برای دریافت لحظه‌ای پیام‌ها (Polling)
    app.run_polling()

قدم پنجم: اجرای ربات

در ترمینال (یا CMD)، به مسیری که فایل bot.py را در آن ذخیره کرده‌اید بروید و دستور زیر را تایپ کنید:

python bot.py

اگر پیغام ✅ Bot is ruing! را مشاهده کردید، تبریک می‌گوییم! ربات شما آماده کار است. وارد تلگرام شوید، ربات خود را استارت کنید و پس از آن دستور /profile را بفرستید تا بازده فوق‌العاده دیتابیس را به چشم ببینید.

در این بخش به پرتکرارترین و مهم‌ترین سوالاتی که توسعه‌دهندگان ربات‌های تلگرامی با آن مواجه می‌شوند، پاسخ داده‌ایم:

ربات شما یک اسکریپت پایتون است که در حافظه رم کامپیوتر شما در حال اجراست. با خاموش شدن سیستم یا قطع اینترنت، اسکریپت متوقف می‌شود. برای فعالیت ۲۴ ساعته، باید ربات و دیتابیس خود را به یک سرور مجازی (VPS) لینوکسی یا سرویس‌های ابری (مثل لیارا، پایتون‌انی‌ور یا هروکو) منتقل کنید تا کد شما در آنجا همیشه روشن بماند.

قرار دادن توکن و رمز دیتابیس به صورت متن ساده داخل کد (Hardcoding) کار خطرناکی است (مخصوصاً اگر کد را در گیت‌هاب منتشر کنید). راه حل حرفه‌ای، استفاده از فایل‌های .env است. کتابخانه python-dotenv را نصب کنید، یک فایل به نام .env بسازید و توکن را آنجا بگذارید. سپس در پایتون با استفاده از os.getenv('BOT_TOKEN') آن را فراخوانی کنید.

بله، دقیقاً! کتابخانه python-telegram-bot از تمام تواناییات تلگرام پشتیبانی می‌کند. برای ساخت دکمه‌های شیشه‌ای که زیر پیام می‌چسبند، می‌توانید از کلاس‌های InlineKeyboardMarkup و InlineKeyboardButton در این کتابخانه استفاده کنید و برای مدیریت کلیک روی آن‌ها، یک CallbackQueryHandler بنویسید.

شما chat_id تمام کاربران را در جدول users دارید. کافیست یک اسکریپت پایتون بنویسید که:

برای مدیریت پیام‌های متنی، تصویرها، صداها و… باید علاوه بر CommandHandler، از MessageHandler استفاده کنید. مثلاً: app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, my_text_function)) این کد باعث می‌شود هر پیام متنی که با اسلش (/) آغاز نشده باشد، به تابع my_text_function فرستاده شود.

در آموزش بالا، ما از متد ارسال پارامتر ایمن (Parameterized Queries) استفاده کردیم: cursor.execute("SELECT * FROM users WHERE chat_id = %s", (chat_id,)) استفاده از %s و پاس دادن متغیرها به عنوان تاپل (chat_id,) باعث می‌شود که درایور MySQL به طور خودکار ورودی‌ها را پاکسازی (Sanitize) کند و جلوی حملات تزریق کد (SQL Injection) مفصلاً گرفته شود.

سخن پایان کاری: تبریک می‌گویم! شما اکنون دانش ساخت یک ربات تلگرامی پایگاه‌داده‌محور را در اختیار دارید. این ساختار (پایتون + کتابخانه نسخه جدید ۲۰ به بالا + دیتابیس رابطه‌ای) استانداردی است که در پروژه‌های واقعی و تجاری استفاده می‌شود. قدم بعدی شما می‌تواند ساخت پنل ادمین، اتصال به درگاه پرداخت واسط (مثل زرین‌پال) و پیاده‌سازی دکمه‌های شیشه‌ای باشد. کدنویسی خوش بگذرد!

نوشته آموزش ساخت ربات تلگرام با پایتون و اتصال به پایگاه داده MySQL اولین بار در رایا پروژه. پدیدار شد.