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

آموزش ساخت ربات تلگرام با aiogram 🐍🤖

سلام! 👋 اگر Python را تا حد توابع بلد هستید، تقریباً آماده‌اید که وارد دنیای ساخت Telegram Bot شوید.

در این آموزش با کتابخانه‌ی aiogram یاد می‌گیریم چطور ربات‌های تلگرامی بسازیم؛ از یک ربات بسیار ساده شروع می‌کنیم و قدم‌به‌قدم به مفاهیمی مثل:

• دریافت پیام‌ها
• پاسخ دادن به کاربران
• Commandها
• Handlerها
• دکمه‌ها
• دریافت اطلاعات از کاربر
• FSM
• Callback Query
• Inline Keyboard
• Middleware
• ساختار حرفه‌ای پروژه
• کار با دیتابیس
• و در نهایت ساخت یک ربات واقعی

می‌رسیم.

فصل‌های دوره

مسیر کلی آموزش به این شکل خواهد بود:

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

بخش ۱ — aiogram چیست؟ 🤔

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

Telegram Bot چیست؟

ربات تلگرام برنامه‌ای است که از طریق Telegram Bot API با کاربران ارتباط برقرار می‌کند.

برای مثال کاربر می‌فرستد:

سلام

و ربات پاسخ می‌دهد:

سلام! خوش آمدی 👋

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

/start

و ربات پاسخ می‌دهد:

سلام! من یک ربات هستم 🤖

aiogram چیست؟

aiogram یک کتابخانه‌ی Python برای کار با Telegram Bot API است.

در حالت ساده، می‌توانیم جریان را این‌گونه تصور کنیم:

User
  │
  │  Message
  ▼
Telegram
  │
  │  Bot API
  ▼
aiogram
  │
  ▼
Python Code
  │
  ▼
Response

یعنی aiogram بسیاری از جزئیات ارتباط با Telegram API را برای ما مدیریت می‌کند.

به‌جای اینکه خودمان درخواست‌های HTTP زیادی بنویسیم، می‌توانیم با Python چیزی شبیه این بنویسیم:

@router.message()
async def hello(message):
    await message.answer("Hello!")

و aiogram بخش بزرگی از ارتباط با Telegram را برای ما انجام می‌دهد.

چرا aiogram؟

چند کتابخانه‌ی مختلف برای ساخت Telegram Bot در Python وجود دارد.

یکی از انتخاب‌های مهم، aiogram است.

مزایای مهم آن:

• Pythonic بودن
• پشتیبانی مناسب از async/await
• سیستم قدرتمند Handler
• سیستم Filter
• Router
• Middleware
• FSM
• مناسب بودن برای پروژه‌های نسبتاً بزرگ

البته aiogram تنها انتخاب موجود نیست و کتابخانه‌های دیگری هم وجود دارند. اما در این دوره تمرکز ما روی aiogram است.

async یعنی چه؟

قبل از شروع جدی با aiogram، یک نکته‌ی مهم وجود دارد.

aiogram به‌شدت از Asynchronous Programming استفاده می‌کند.

بنابراین به‌جای:

def hello():
    ...

زیاد با این ساختار مواجه خواهید شد:

async def hello():
    ...

و برای انجام عملیات asynchronous نیز معمولاً از:

await

استفاده می‌کنیم.

مثلاً:

async def hello():
    result = await something()

فعلاً لازم نیست asyncio را عمیق یاد بگیرید.

در طول دوره، زمانی که به async و await برسیم، آن‌ها را با مثال‌های ساده توضیح می‌دهیم.

یک مثال خیلی ساده

حتی بدون ساختن Bot، می‌توانیم شکل یک تابع asynchronous را ببینیم:

import asyncio


async def hello():
    print("Hello from aiogram!")


asyncio.run(hello())

خروجی:

Hello from aiogram!

در این مثال هنوز از aiogram استفاده نکرده‌ایم.

هدف فقط این است که با ظاهر کدهای asynchronous آشنا شوید.

تمرین ✏️

کد بالا را اجرا کنید.

سپس متن:

Hello from aiogram!

را به چیزی مثل:

Hello Telegram Bot!

تغییر دهید.

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

اگر خطایی دیدید یا چیزی برایتان نامفهوم بود، همان خطا یا سؤال را در کامنت بنویسید.

بخش ۲ — ساخت Bot در Telegram 🤖

حالا وقت ساخت اولین Bot است.

برای ساخت Bot باید از BotFather در Telegram استفاده کنیم.

در Telegram به BotFather بروید و یک Bot جدید بسازید.

BotFather به شما یک Bot Token می‌دهد.

Token چیزی شبیه این است:

123456789:AAExampleExampleExample

⚠️ Token را با کسی به اشتراک نگذارید.

Token تقریباً مثل رمز عبور Bot شماست.

نصب aiogram

برای نصب aiogram می‌توانیم از pip استفاده کنیم:

pip install aiogram

بعد می‌توانیم بررسی کنیم که نصب شده است یا نه:

pip show aiogram

اولین Bot

حالا یک فایل مثلاً با نام:

bot.py

بسازید.

کد اولیه:

import asyncio

from aiogram import Bot, Dispatcher


TOKEN = "YOUR_BOT_TOKEN"


async def main():
    bot = Bot(token=TOKEN)
    dp = Dispatcher()

    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

بیایید خط‌به‌خط بررسی کنیم.

Bot

این قسمت:

bot = Bot(token=TOKEN)

یک Object از Bot ایجاد می‌کند.

Token به aiogram می‌گوید که باید با کدام Telegram Bot کار کند.

Dispatcher

این قسمت:

dp = Dispatcher()

یک Dispatcher ایجاد می‌کند.

فعلاً می‌توانیم خیلی ساده بگوییم Dispatcher مسئول مدیریت جریان دریافت Updateها و پیدا کردن Handler مناسب است.

بعداً دقیق‌تر با آن کار می‌کنیم.

start_polling

این خط:

await dp.start_polling(bot)

باعث می‌شود Bot شروع به دریافت Updateها از Telegram کند.

در نتیجه برنامه تا زمانی که Bot در حال اجراست، منتظر پیام‌ها می‌ماند.

اجرای Bot

حالا:

python bot.py

را اجرا کنید.

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

حالا به Bot خود در Telegram پیام بدهید.

اما یک مشکل داریم:

هنوز به هیچ پیامی پاسخ نمی‌دهد!

چرا؟

چون هنوز هیچ Handlerای تعریف نکرده‌ایم.

بخش ۳ — اولین Handler 🎯

Handler را می‌توان تقریباً به شکل زیر تصور کرد:

«اگر چنین چیزی اتفاق افتاد، این تابع را اجرا کن.»

مثلاً:

اگر کاربر /start فرستاد
        ↓
تابع start را اجرا کن

یک مثال:

import asyncio

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message


TOKEN = "YOUR_BOT_TOKEN"


async def start_handler(message: Message):
    await message.answer("سلام! 👋")


async def main():
    bot = Bot(token=TOKEN)
    dp = Dispatcher()

    dp.message.register(start_handler, CommandStart())

    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

حالا اگر کاربر:

/start

را بفرستد، این تابع اجرا می‌شود:

async def start_handler(message: Message):
    await message.answer("سلام! 👋")

Message چیست؟

در این تابع:

async def start_handler(message: Message):

متغیر:

message

اطلاعات مربوط به پیام کاربر را در اختیار ما قرار می‌دهد.

برای مثال می‌توانیم به اطلاعاتی مثل این‌ها دسترسی داشته باشیم:

message.text

متن پیام

یا:

message.from_user

اطلاعات کاربر فرستنده

و موارد بسیار دیگر.

message.answer()

این خط:

await message.answer("سلام! 👋")

به کاربر پاسخ می‌دهد.

در نتیجه:

User
 │
 │ /start
 ▼
Telegram
 │
 ▼
aiogram
 │
 ▼
start_handler()
 │
 ▼
message.answer()
 │
 ▼
Telegram
 │
 ▼
User

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

یک نکته مهم درباره await

دقت کنید که نوشتیم:

await message.answer(...)

و نه:

message.answer(...)

چون ارسال پیام یک عملیات asynchronous است.

بنابراین معمولاً آن را با await اجرا می‌کنیم.

بخش ۴ — Handler برای پیام‌های معمولی 💬

حالا می‌خواهیم کاری کنیم که Bot به یک پیام معمولی پاسخ بدهد.

مثلاً:

User:
سلام

Bot:
سلام! خوبی؟ 😄

کد:

import asyncio

from aiogram import Bot, Dispatcher
from aiogram.types import Message


TOKEN = "YOUR_BOT_TOKEN"


async def message_handler(message: Message):
    await message.answer("پیامت رو دریافت کردم! 😄")


async def main():
    bot = Bot(token=TOKEN)
    dp = Dispatcher()

    dp.message.register(message_handler)

    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

در اینجا:

dp.message.register(message_handler)

می‌گوید پیام‌های دریافتی را به این Handler بسپار.

یک مشکل کوچک

اگر این کد را اجرا کنید، تقریباً هر پیام باعث اجرای این تابع می‌شود:

async def message_handler(message: Message):
    await message.answer("پیامت رو دریافت کردم! 😄")

مثلاً:

سلام

یا:

123

یا:

Python

همگی پاسخ یکسان می‌گیرند.

اما ما معمولاً نمی‌خواهیم این‌طور باشد.

مثلاً می‌خواهیم بگوییم:

فقط وقتی متن پیام سلام بود، این تابع را اجرا کن.

اینجاست که Filterها وارد می‌شوند.

بخش ۵ — Filterها 🔎

Filter مشخص می‌کند یک Handler برای چه Updateهایی اجرا شود.

مثلاً:

from aiogram import F

و:

dp.message.register(message_handler, F.text == "سلام")

یعنی:

اگر پیام یک متن بود
        +
متن دقیقاً "سلام" بود
        ↓
message_handler اجرا شود

کد کامل:

import asyncio

from aiogram import Bot, Dispatcher, F
from aiogram.types import Message


TOKEN = "YOUR_BOT_TOKEN"


async def hello_handler(message: Message):
    await message.answer("سلام! 👋")


async def main():
    bot = Bot(token=TOKEN)
    dp = Dispatcher()

    dp.message.register(hello_handler, F.text == "سلام")

    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

حالا:

سلام

پاسخ می‌گیرد، ولی:

خوبی؟

نه.

چرا Filter مهم است؟

در یک Bot واقعی ممکن است صدها Handler داشته باشیم:

/start
/help
/register
/login
پیام متنی
عکس
فایل
دکمه
Callback
...

aiogram باید بداند هر Update را به کدام Handler بدهد.

Filterها یکی از ابزارهای اصلی برای کنترل این موضوع هستند.

بخش ۶ — Router چیست؟ 🛣️

وقتی پروژه کوچک باشد، شاید این ساختار کافی باشد:

dp.message.register(...)
dp.callback_query.register(...)

اما وقتی پروژه بزرگ شود، داشتن تمام Handlerها در یک فایل ایده خوبی نیست.

مثلاً ممکن است داشته باشیم:

bot/
├── main.py
├── handlers/
│   ├── start.py
│   ├── help.py
│   ├── registration.py
│   └── admin.py
└── ...

در چنین شرایطی Router بسیار مهم می‌شود.

یک Router می‌تواند Handlerهای مربوط به یک قسمت از Bot را در خود نگه دارد.

مثلاً:

from aiogram import Router

router = Router()

و بعد:

@router.message(...)
async def ...

سپس Router را به Dispatcher متصل می‌کنیم.

بخش ۷ — Syntax دکوراتورها

تا اینجا از:

dp.message.register(...)

استفاده کردیم.

اما در aiogram زیاد این شکل را هم خواهید دید:

@router.message(...)
async def hello(message: Message):
    ...

این یک Decorator است.

اگر هنوز Decoratorهای Python را یاد نگرفته‌اید، نگران نباشید؛ برای ادامه‌ی دوره می‌توانیم آن را از پایه و با مثال ساده یاد بگیریم.

مثلاً:

@router.message(F.text == "سلام")
async def hello(message: Message):
    await message.answer("سلام! 👋")

می‌توانیم آن را به‌صورت مفهومی این‌طور بخوانیم:

این تابع را به عنوان Handler پیام‌هایی که متنشان «سلام» است ثبت کن.

اولین پروژه کوچک 🎉

تا اینجا می‌توانیم یک Bot کوچک بسازیم که:

• /start را دریافت کند.
• به «سلام» پاسخ دهد.
• به پیام‌های معمولی پاسخ دهد.

ساختار:

import asyncio

from aiogram import Bot, Dispatcher, F, Router
from aiogram.filters import CommandStart
from aiogram.types import Message


TOKEN = "YOUR_BOT_TOKEN"

router = Router()


@router.message(CommandStart())
async def start(message: Message):
    await message.answer(
        "سلام! 👋\n"
        "به ربات من خوش اومدی!"
    )


@router.message(F.text == "سلام")
async def hello(message: Message):
    await message.answer("سلام! 😄")


async def main():
    bot = Bot(token=TOKEN)

    dp = Dispatcher()
    dp.include_router(router)

    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

این کد اولین نقطه‌ای است که ساختار واقعی‌تری از یک Bot aiogram را می‌بینیم.

🧠 تا اینجا چه چیزهایی یاد گرفتیم؟

اگر این قسمت‌ها را متوجه شده باشید، پایه‌ی خوبی دارید:

Bot
 │
 ├── Dispatcher
 │
 ├── Router
 │     │
 │     ├── Handler
 │     ├── Handler
 │     └── Handler
 │
 └── Polling

و مفاهیم:

Bot

ارتباط با Telegram Bot API.

Dispatcher

مدیریت Updateها و اجرای Handlerهای مناسب.

Router

دسته‌بندی Handlerها.

Handler

تابعی که در صورت برقرار شدن شرایط مشخص اجرا می‌شود.

Filter

تعیین می‌کند Handler برای چه Updateهایی مناسب است.

Message

اطلاعات مربوط به یک پیام Telegram.

📝 تمرین این بخش

یک Bot بسازید که این رفتار را داشته باشد:

User:
 /start

Bot:
سلام! به ربات من خوش آمدی 🤖

و:

User:
سلام

Bot:
سلام! چه خبر؟ 😄

و برای:

User:
خداحافظ

Bot:
خداحافظ! 👋

یک Handler جدا داشته باشد.

راهنمایی:

@router.message(F.text == "خداحافظ")
async def goodbye(message: Message):
    ...

🚀 مرحله بعد

در بخش بعدی می‌توانیم وارد یکی از جذاب‌ترین قسمت‌های aiogram شویم:

Keyboardها و دکمه‌های Telegram

مثلاً:

┌──────────────┬──────────────┐
│   درباره ما   │   محصولات    │
├──────────────┼──────────────┤
│    تماس       │    کمک ❓     │
└──────────────┴──────────────┘

و یاد می‌گیریم چطور وقتی کاربر روی یک دکمه کلیک کرد، Bot بفهمد کدام دکمه انتخاب شده و چه کاری انجام دهد.

کدهای هر بخش را می‌توانید در همین پلتفرم اجرا کنید؛ اگر جایی خطا گرفتید یا مفهوم خاصی مثل async/await، Router، Filter یا Decorator برایتان مبهم بود، همان کد و خطا را کامنت کنید تا دقیقاً از همان‌جا ادامه بدهیم.