آموزش ساخت ربات تلگرام با پایتون (راهنمای جامع ۲۰۲۶)

رباتهای تلگرام یکی از قدرتمندترین و پرکاربردترین بسترها برای ارائه خدمات خودکار، سامانههای تعاملی، پشتیبانی مشتریان و ابزارهای هوشمند هستند. با عرضه نسخههای مدرن فریمورک python-telegram-bot (v20+)، معماری پیادهسازی رباتهای تلگرام به طور بنیادین بر پایه برنامهنویسی ناهمگام (Async/Await) بازطراحی شده است؛ این تغییر ساختاری امکان پاسخدهی همزمان و با تأخیر نزدیک به صفر را برای صدها کاربر بدون مسدود شدن منابع سرور فراهم میکند.
پاسخ کوتاه: برای ساخت یک ربات تلگرام مدرن با پایتون در سال ۲۰۲۶، ابتدا از ربات رسمی @BotFather یک توکن API اختصاصی دریافت میکنید، کتابخانه python-telegram-bot را نصب کرده و با استفاده از ApplicationBuilder، هندلرهای غیرهمگام دستورات (CommandHandler) و دکمههای شیشهای (CallbackQueryHandler) را تعریف مینمایید.
در این مقاله، راهنمای گامبهگام طراحی و پیادهسازی یک ربات تلگرام تعاملی، ماژولار و استاندارد را به همراه پیادهسازی دکمههای شیشهای، خواندن امن توکن و دسترسی به سورس کد کامل در گیتهاب بررسی میکنیم.
پیشنیازها
برای پیادهسازی این پروژه به موارد زیر نیاز دارید:
- پایتون ۳.۱۰ یا بالاتر (اگر هنوز محیط پایتون را آماده نکردهاید، راهنمای نصب پایتون در ویندوز را مطالعه کنید).
- یک حساب کاربری فعال تلگرام برای ثبت ربات و دریافت توکن دسترسی.
- یک ویرایشگر کد مانند VS Code.
گام اول: ساخت ربات و دریافت توکن از BotFather
تمامی رباتها در بستر تلگرام توسط ربات مادری به نام BotFather ثبت و مدیریت میشوند.
- در پیامرسان تلگرام، شناسه
@BotFatherرا جستوجو کرده و وارد گفتوگو شوید (حتماً نشان تأیید آبی تلگرام را بررسی نمایید). - دستور
/newbotرا ارسال کنید. - یک نام نمایشی (Display Name) برای ربات خود وارد کنید (برای نمونه:
Taha Assistant Bot). - یک نام کاربری (Username) برای ربات تعیین کنید. این نام باید یکتا بوده و حتماً با پسوند
botخاتمه یابد (برای نمونه:taha_dev_starter_bot). - پس از تأیید، BotFather پیامی حاوی HTTP API Token اختصاصی شما صادر میکند (رشتهای به فرم
123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
⚠️ نکته امنیتی حیاتی: توکن ربات حکم کلید اصلی حساب آن است. هرگز این توکن را در سورس کدهای عمومی یا ریپازیتوریهای گیت کامیت نکنید و همواره آن را در قالب متغیرهای محیطی (
.env) ایزوله نگه دارید.
گام دوم: راهاندازی پروژه و ساخت محیط ایزوله (venv)
ابتدا یک دایرکتوری جدید برای پروژه ایجاد کرده و محیط مجازی پایتون را فعال نمایید:
mkdir telegram-bot-starter
cd telegram-bot-starter
python -m venv .venv
فعالسازی محیط مجازی در ویندوز:
.venv\Scripts\activate
فعالسازی محیط مجازی در لینوکس یا مک:
source .venv/bin/activate
سپس پکیجهای استاندارد مورد نیاز را نصب کنید:
pip install "python-telegram-bot[job-queue]" python-dotenv
- python-telegram-bot: فریمورک استاندارد، تایپسیف و مدرن کار با Telegram Bot API.
- python-dotenv: جهت بارگذاری امن متغیرهای محیطی از فایل
.env.
گام سوم: پیکربندی امن توکن در فایل .env
فایلی با نام .env در ریشه پروژه ایجاد کرده و توکن خود را در آن وارد کنید:
TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN_HERE
جهت اطمینان از عدم آپلود اشتباهی متغیرها در گیت، فایل .gitignore را با محتوای زیر بسازید:
.venv/
.env
__pycache__/
*.pyc
گام چهارم: درک معماری ناهمگام (Async) در نسخههای جدید فریمورک
در نسخه ۲۰ به بعد python-telegram-bot کل کتابخانه بر اساس کتابخانه asyncio بازنویسی شده است. ویژگیهای کلیدی این معماری عبارتند از:
- تمامی هندلرها به صورت توابع
async defپیادهسازی میشوند. - ارسال پیامها و پاسخ به رویدادها با استفاده از کلمه کلیدی
awaitصورت میگیرد. - کلاسی به نام
ApplicationBuilderمسئولیت ساخت، پیکربندی چرخهحیات و اتصال تمامی ماژولها به یکدیگر را به عهده دارد.
گام پنجم: پیادهسازی سورس کد کامل ربات (bot.py)
فایلی با نام bot.py در پوشه پروژه بسازید و کدهای استاندارد زیر را در آن قرار دهید:
import os
import logging
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import (
ApplicationBuilder,
CommandHandler,
ContextTypes,
CallbackQueryHandler,
MessageHandler,
filters,
)
# بارگذاری متغیرهای محیطی
load_dotenv()
BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
# تنظیمات سیستم لاگینگ
logging.basicConfig(
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
level=logging.INFO,
)
logger = logging.getLogger(__name__)
# هندلر دستور شروع /start
async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
user = update.effective_user
welcome_message = (
f"سلام {user.first_name} عزیز! 👋\n\n"
"به ربات پایتونی نمونه خوش آمدید.\n"
"از دکمههای شیشهای زیر جهت دسترسی سریع به بخشها استفاده کنید:"
)
# طراحی دکمههای شیشهای (Inline Keyboard)
keyboard = [
[
InlineKeyboardButton("🌐 مشاهده وبسایت", url="https://taha-heidaryfard.ir"),
InlineKeyboardButton("📂 نمونهکارها", url="https://taha-heidaryfard.ir/projects"),
],
[
InlineKeyboardButton("⚡ وضعیت سرویس", callback_data="status_check"),
InlineKeyboardButton("ℹ️ درباره سازنده", callback_data="about_author"),
],
]
reply_markup = InlineKeyboardMarkup(keyboard)
await update.message.reply_text(
text=welcome_message,
reply_markup=reply_markup,
)
# هندلر دستور راهنما /help
async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
help_text = (
"📖 **راهنمای استفاده از ربات:**\n\n"
"• `/start` — راهاندازی و باز کردن منوی تعاملی\n"
"• `/help` — نمایش این پیام راهنما\n"
"• ارسال هر پیام متنی ساده برای دریافت پاسخ اکو از سرور"
)
await update.message.reply_text(help_text, parse_mode="Markdown")
# پردازش کلیک روی دکمههای شیشهای (Inline Callbacks)
async def button_callback_handler(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
query = update.callback_query
# اطلاع به تلگرام برای بستن انیمیشن لودینگ دکمه در کلاینت کاربر
await query.answer()
data = query.data
if data == "status_check":
await query.edit_message_text(
text="✅ **وضعیت سرور:** ربات به صورت کاملاً غیرهمگام، آنلاین و آماده پاسخگویی است.",
parse_mode="Markdown",
)
elif data == "about_author":
await query.edit_message_text(
text=(
"👨💻 **درباره توسعهدهنده:**\n"
"طراحی و پیادهسازی شده توسط محمد طاها حیدریفرد\n"
"توسعهدهنده سیستمهای وب، بکاند و پایتون."
),
parse_mode="Markdown",
)
# هندلر پردازش پیامهای متنی عادی
async def echo_message_handler(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
received_text = update.message.text
response = f"پیام شما دریافت شد: «{received_text}»"
await update.message.reply_text(response)
# مدیریت مرکزی خطاها
async def error_handler(update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
logger.error("خطای سیستمی در اجرای هندلرها:", exc_info=context.error)
def main() -> None:
if not BOT_TOKEN:
raise ValueError("خطا: توکن TELEGRAM_BOT_TOKEN در فایل .env مقداردهی نشده است!")
# ساخت کلاینت اپلیکیشن ربات
app = ApplicationBuilder().token(BOT_TOKEN).build()
# ثبت هندلرهای دستورات و رویدادها
app.add_handler(CommandHandler("start", start_command))
app.add_handler(CommandHandler("help", help_command))
app.add_handler(CallbackQueryHandler(button_callback_handler))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo_message_handler))
# ثبت ناظر مرکزی خطاها
app.add_error_handler(error_handler)
# اجرای دریافت مداوم پیامها (Polling)
print("🚀 ربات با موفقیت راهاندازی شد. در حال گوش دادن به پیامها...")
app.run_polling(drop_pending_updates=True)
if __name__ == "__main__":
main()
گام ششم: اجرای ربات و آزمایش در تلگرام
برای تست و راهاندازی ربات، دستور زیر را در ترمینال اجرا کنید:
python bot.py
با مشاهده پیام راهاندازی موفق در ترمینال، به تلگرام بازگشته، دکمه Start را لمس کنید و پاسخها و دکمههای شیشهای را تست نمایید.
نکات مهندسی و الگوهای اصولی در توسعه ربات
- استفاده از
drop_pending_updates=True: این قابلیت باعث میشود در زمان راهاندازی مجدد برنامه، پیامهایی که در زمان قطعی ارسال شده بودند به یکباره پردازش نشوند و پردازنده سرور تحت بار ناگهانی قرار نگیرد. - جداسازی Inline Keyboard از Reply Keyboard: دکمههای شیشهای (
InlineKeyboardMarkup) به دلیل واکنشپذیری بالا، چیدمان منعطف و عدم شلوغ کردن کیبورد کاربر، استاندارد اول در ساخت رابطهای کاربری تلگرام مدرن هستند. - هندلر عمومی خطا (
add_error_handler): همیشه خطاهای رخداده را لاگ کنید تا خطاهای پیشبینینشده کلاینت باعث توقف کل برنامه نشود.
لینک مخزن سورسکد در گیتهاب
سورس کامل و تستشده این پروژه همراه با فایلهای پیکربندی و ساختار استاندارد در گیتهاب منتشر شده است:
👉 github.com/taha-heidaryfard/python-telegram-bot-starter
سوالات متداول
تفاوت Polling و Webhook چیست؟
در حالت Polling، برنامه پایتون در بازههای زمانی کوتاه از سرورهای تلگرام درخواست دریافت پیامهای جدید میکند. این شیوه برای محیط توسعه محلی و باتهای سبک بسیار ایدهآل است چرا که به دامین اختصاصی یا گواهی SSL نیازی ندارد. در حالت Webhook، سرور تلگرام به ازای هر آپدیت یک وبهوک به آدرس امن سرور شما ارسال میکند.
آیا استفاده از تلگرام بات API رایگان است؟
بله؛ پلتفرم رسمی بات تلگرام کاملاً رایگان بوده و برای ایجاد ربات، ارسال پیامهای نامحدود متنی، تصویری و تعاملی هیچگونه اشتراک یا هزینهای دریافت نمیکند.
چرا باید از نسخه ۲۰ به بعد python-telegram-bot استفاده کنیم؟
در نسخههای قبلی، معماری برنامه به صورت Blocking بود و پردازش درخواستهای سنگین باعث مسدود شدن صف بقیه کاربران میشد. از نسخه ۲۰ به بعد، کل فریمورک بر پایه قابلیتهای نیتیو async/await در پایتون ۳ بازنویسی شده که کارایی بسیار بالاتری ارائه میدهد.
برچسبهای این مقاله:
