Aiogram docs: как начать писать Telegram-бота

Aiogram — это Python-фреймворк для Telegram-ботов. В актуальной ветке aiogram 3 бот обычно строится вокруг Bot, Dispatcher, async-функций и handlers, которые реагируют на команды и сообщения

Начинать лучше с минимального бота: установить aiogram, сохранить токен в переменную окружения, добавить обработчик /start и запустить polling

Установка

pip install aiogram

Токен бота получите у BotFather и сохраните в переменную окружения

export BOT_TOKEN='ваш_токен'

$env:BOT_TOKEN = 'ваш_токен'

Не храните токен прямо в коде и не публикуйте его в репозитории

Минимальный бот на aiogram 3

Создайте файл bot.py

import asyncio
import os

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

dp = Dispatcher()

@dp.message(CommandStart())
async def start_handler(message: Message):
    await message.answer('Привет. Бот работает')

async def main():
    bot = Bot(token=os.environ['BOT_TOKEN'])
    await dp.start_polling(bot)

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

Запуск:

python bot.py

После запуска откройте бота в Telegram и отправьте /start. Бот должен ответить сообщением Привет. Бот работает

По этой теме полезно отдельно посмотреть Составьте еженедельное расписание занятий, чтобы расширить контекст и сравнить подходы

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы

Что делает этот код

Bot хранит токен и отправляет запросы к Telegram Bot API

Dispatcher принимает updates и передает их подходящим handlers

@dp.message(CommandStart()) регистрирует обработчик команды /start

Message — объект сообщения от пользователя

await message.answer() отправляет ответ

dp.start_polling(bot) запускает получение updates через polling

Echo-бот

Добавим обработчик обычного текста

from aiogram import F

@dp.message(F.text)
async def echo_handler(message: Message):
    await message.answer(f'Вы написали: {message.text}')

Полный файл может выглядеть так:

import asyncio
import os

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

dp = Dispatcher()

@dp.message(CommandStart())
async def start_handler(message: Message):
    await message.answer('Привет. Напишите любой текст')

@dp.message(F.text)
async def echo_handler(message: Message):
    await message.answer(f'Вы написали: {message.text}')

async def main():
    bot = Bot(token=os.environ['BOT_TOKEN'])
    await dp.start_polling(bot)

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

Порядок handlers важен. Команду /start лучше обработать отдельным handler, а общий текстовый обработчик оставить ниже

Router для роста проекта

Когда бот становится больше, handlers часто выносят в Router

from aiogram import Router

router = Router()

@router.message(CommandStart())
async def start_handler(message: Message):
    await message.answer('Старт')

dp.include_router(router)

Для первого файла Dispatcher без отдельного router нормален. Router понадобится, когда появятся разные группы handlers: меню, админка, заявки, платежи

Частые ошибки

Использовать примеры aiogram 2.x в проекте aiogram 3

Хранить токен в коде

Забыть await перед отправкой сообщения

Запустить два polling-процесса одного и того же бота

Не импортировать нужный filter, например CommandStart

Поставить слишком общий handler выше специального

Как читать aiogram docs

Сначала смотрите установку и минимальный пример

Потом ищите разделы про Dispatcher, Router, filters и types

Если пример из интернета не работает, проверьте версию aiogram. Ветка 2.x и ветка 3.x отличаются синтаксисом

Когда нужен новый тип сообщения, ищите соответствующий types: Message, CallbackQuery, InlineKeyboardMarkup

Практические задачи

Сделайте ответ на /start

Добавьте echo-обработчик текста

Добавьте команду /help

Сохраните токен в переменную окружения

Вынесите handlers в Router

Проверьте, что бот не запущен одновременно в двух терминалах

Чтобы начать писать Telegram-бота на aiogram, установите библиотеку, сохраните токен вне кода, создайте Bot и Dispatcher, добавьте handler команды /start и запустите dp.start_polling(bot)

Для новых проектов используйте синтаксис aiogram 3. Если находите старые примеры, сначала проверяйте, к какой версии они относятся