آموزش ساخت اکو بات تلگرام با Aiogram (ساخت بات تلگرام با پایتون مرحله به مرحله)

چطور در پایتون یک بات تلگرام بنویسیم!

علی حیدری ۱۴۰۵/۰۲/۰۵ ۸۴ ۷ دقیقه

آموزش ساخت اکو بات تلگرام با Aiogram (ساخت بات تلگرام با پایتون مرحله به مرحله)

کتابخانه aiogram یکی از محبوب‌ترین و سریع‌ترین فریم‌ورک‌ها برای ساخت ربات‌های تلگرام با زبان پایتون است. این کتابخانه بر پایه معماری آسنکرون پایتون و کتابخانه asyncio ساخته شده و به همین دلیل عملکرد بسیار سریع و بهینه‌ای در مدیریت پیام‌ها و درخواست‌ها دارد. توسعه‌دهندگان زیادی از aiogram استفاده می‌کنند چون علاوه بر سرعت بالا، ساختار تمیز و قابل‌مدیریتی برای پروژه‌های ربات تلگرام ارائه می‌دهد و هم برای پروژه‌های کوچک و هم برای پروژه‌های بزرگ و حرفه‌ای انتخاب مناسبی محسوب می‌شود.

در این مقاله قصد داریم یک اکو بات یا Echo Bot بسازیم. اکو بات نوعی ربات ساده است که هر پیامی را از کاربر دریافت کند، همان پیام را دوباره برای او ارسال می‌کند. با وجود سادگی این ایده، پیاده‌سازی آن کمک می‌کند تا با مفاهیم پایه‌ای توسعه ربات تلگرام آشنا شوید و درک بهتری از نحوه کار aiogram به دست آورید.

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

شروع پروژه

مرحله ۱: نصب aiogram

ابتدا یک محیط مجازی ایجاد کن (اختیاری اما خیلی بهتر است):

python -m venv venv
source venv/bin/activate  # لینوکس / مک
venv\Scripts\activate     # ویندوز

حالا aiogram را نصب می‌کنیم:

pip install aiogram

چرا این مرحله را انجام دادیم؟

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

این نقطهٔ شروع هر پروژه تلگرامی است.

مرحله ۲: ساخت Bot Token در تلگرام

برای ساخت ربات باید به ربات رسمی تلگرام یعنی:

@BotFather

پیام بدهی.

سپس دستور زیر را وارد کن:

/newbot

BotFather از تو می‌پرسد:

  • یک نام برای ربات
  • یک یوزرنیم (که با bot_ ختم شود)

در نهایت یک توکن به تو می‌دهد:

123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

چرا این مرحله مهم است؟

توکن کلید ارتباطی بین ربات و تلگرام است.
هر درخواستی که ربات از سمت پایتون به تلگرام می‌فرستد باید با این توکن انجام شود.

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

مرحله ۳: ساخت فایل bot.py برای اجرای ربات

فایل bot.py را بساز و این کد را داخلش قرار بده:

from aiogram import Bot, Dispatcher, executor, types

API_TOKEN = "YOUR_BOT_TOKEN_HERE"

bot = Bot(token=API_TOKEN)
dp = Dispatcher(bot)

@dp.message_handler()
async def echo_message(message: types.Message):
    await message.answer(message.text)

if __name__ == "__main__":
    executor.start_polling(dp)

حالا این کد را مرحله‌به‌مرحله توضیح می‌دهیم.

تحلیل خط به خط کد

۱. ایمپورت‌ کردن کلاس‌های اصلی

from aiogram import Bot, Dispatcher, executor, types

این خط aiogram را وارد پروژه می‌کند.

  • Bot → وظیفهٔ ارتباط با API تلگرام
  • Dispatcher → مدیریت پیام‌ها و هندلرها
  • executor → اجرای ربات و polling
  • types → مدل‌های داده‌ای (Message, User, Chat و...)

این چهار جزء تقریباً در تمام پروژه‌های aiogram وجود دارند.

۲. تنظیم توکن ربات

API_TOKEN = "YOUR_BOT_TOKEN_HERE"

اینجا Token بات را قرار می‌دهیم.
این مقدار در کل پروژه لازم است.

۳. ساخت شیء Bot

bot = Bot(token=API_TOKEN)

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

۴. ساخت Dispatcher

dp = Dispatcher(bot)

Dispatcher چیزی شبیه به مغز ربات است.

  • پیام‌ها را دریافت می‌کند
  • بررسی می‌کند کدام هندلر باید اجرا شود
  • پیام‌ها را صف‌بندی می‌کند
  • و کارهای async را مدیریت می‌کند

بدون Dispatcher ربات نمی‌تواند بفهمد چه پیامی را چگونه باید مدیریت کند.

۵. ساخت یک Message Handler

@dp.message_handler()
async def echo_message(message: types.Message):
    await message.answer(message.text)

این قسمت مهم‌ترین بخش پروژه است.

این تابع یک هندلر پیام است.

نقشش چیست؟
هر پیامی که کاربر بفرستد وارد این تابع می‌شود.

  • message: آبجکت پیام کاربر
  • message.text: خود متن پیام
  • message.answer(): ارسال پاسخ به همان چت

چون یک echo bot داریم، متن پیام کاربر را دوباره برمی‌گردانیم.

این ساده‌ترین اما مهم‌ترین نوع هندلر است.

۶. اجرای ربات با Polling

if __name__ == "__main__":
    executor.start_polling(dp)

در این مرحله ربات شروع به کار می‌کند.

Polling یعنی:

  • هر ثانیه پایتون چک می‌کند که آیا پیام جدیدی هست یا نه
  • اگر باشد، آن را به Dispatcher تحویل می‌دهد
  • Dispatcher هندلر مناسب را اجرا می‌کند

Polling برای پروژه‌های کوچک عالی است.
برای پروژه‌های بزرگتر، Webhook پیشنهاد می‌شود.

اجرای ربات

حالا کافی است این دستور را اجرا کنی:

python bot.py

اگر همه‌چیز درست باشد، پیام زیر را در ترمینال می‌بینی:

INFO:aiogram:Bot polling started

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

ارتقا پروژه: مدیریت چند نوع پیام

بیاییم ربات را کمی حرفه‌ای‌تر کنیم.

مثلاً اگر کاربر عکس فرستاد، پیام متنی برگردانیم:

@dp.message_handler(content_types=['photo'])
async def echo_photo(message: types.Message):
    await message.answer("شما یک عکس فرستادید.")

یا اگر فایل صوتی فرستاد:

@dp.message_handler(content_types=['voice'])
async def echo_voice(message: types.Message):
    await message.answer("شما یک ویس ارسال کردید.")

چرا این مرحله را انجام دادیم؟

چون در ربات‌های واقعی، پیام همیشه متن خالص نیست.
باید بتوانیم انواع مختلف پیام را مدیریت کنیم.

اضافه کردن دستورات مثل /start

@dp.message_handler(commands=['start'])
async def start_cmd(message: types.Message):
    await message.answer("سلام! من یک اکو بات هستم. هرچی بفرستی تکرارش می‌کنم.")

چرا این کار مهم است؟

بیشتر ربات‌ها یک پیام خوش‌آمدگویی دارند.
این دقیقاً همان کاری است که کاربران انتظار دارند.

ساختار حرفه‌ای‌تر برای پروژه‌های بزرگتر

وقتی پروژه بزرگ شود، معمولاً کد را به این شکل ساختار می‌دهند:

project/
│ bot.py
│ config.py
│ handlers/
│    ├ start.py
│    ├ echo.py
│    ├ errors.py

اگر خواستی می‌توانم نسخهٔ کامل این ساختار را هم آماده کنم.

علی جان، این بخش را کاملاً متنی، روان، بدون بولد، بدون لیست و یک‌دست بازنویسی کردم:

سخن پایانی

اکو بات ساده‌ترین نوع یک ربات تلگرامی است، اما به‌خوبی مفاهیم اصلی کار با کتابخانه aiogram را منتقل می‌کند. با ساخت همین پروژه کوچک، نحوهٔ مدیریت پیام‌ها، ساخت هندلرها، ماهیت آسنکرون بودن برنامه، نقش Dispatcher در هدایت پیام‌ها و همین‌طور روند Polling را در عمل تجربه می‌کنید. در حقیقت، همین پیاده‌سازی ساده نقطهٔ شروعی برای ورود به دنیای ساخت ربات‌های پیشرفته‌تر است؛ ربات‌هایی که می‌توانند از APIها استفاده کنند، به پرسش‌ها پاسخ بدهند، گروه‌ها را مدیریت کنند، قابلیت‌های هوش مصنوعی داشته باشند یا حتی به‌عنوان یک ابزار کامل برای کسب‌وکار عمل کنند. آشنایی با این پایه‌ها باعث می‌شود مسیر ساخت ربات‌های حرفه‌ای‌تر برای شما بسیار هموارتر و قابل پیش‌بینی‌تر باشد.