Телеграмм бот на Python aiogram 3. Часть 1 / Habr

1. Введение

Это 1 часть практического руководство по созданию Telegram-бота на Python с использованием фреймворка aiogram 3. Его архитектура на базе asyncio позволяет разрабатывать производительные и отзывчивые приложения, способные обрабатывать множество запросов одновременно.

Гайд включает актуальный на 2025 год способ регистрации бота через Mini App в @BotFather.

Цель — предоставить готовую инструкцию, по которой вы с нуля напишете и запустите своего первого эхо-бота. Полученный код станет прочной основой для более сложных проектов. А в конце вас ждет домашнее задание.

2. Шаг 1: Регистрация бота и получение токена через @BotFather Mini App

Для любого взаимодействия с Telegram Bot API требуется уникальный токен аутентификации. Процесс его получения централизован через официального бота @BotFather. С недавнего времени управление ботами было перенесено в более удобный интерфейс Mini App (веб-приложение внутри Telegram), который заменил собой старый консольный метод.

Следуйте этим шагам для регистрации вашего бота:

Откройте диалог с @BotFather. Найдите его через глобальный поиск в Telegram — у официального бота есть синяя галочка верификации. Отправьте ему команду /start.
Запустите Mini App. В сообщении BotFather предложит несколько действий. Нажмите на кнопку меню слева от поля ввода open, который запустит веб-интерфейс управления ботами.

Создайте нового бота. В открывшемся веб-интерфейсе нажмите на кнопку "Create a New Bot".

Задайте имя и юзернейм. Вам будет предложено заполнить два поля:
- Bot Name: Публичное имя, которое пользователи будут видеть в диалоге. Оно может быть любым (например, Мой тестовый бот).
- Bot Username: Уникальный технический идентификатор. Он должен быть написан латиницей, быть уникальным в рамках всего Telegram и обязательно заканчиваться на bot (например, MyTestProjectBot или my_test_project_bot). Система автоматически проверит доступность выбранного юзернейма.

Получите API токен. После успешного создания бота вы будете перенаправлены на страницу его управления. Здесь, в разделе "Token", будет отображена строка вида 1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123456789. Нажмите на нее, чтобы скопировать.

Важно: API токен — это, по сути, пароль от вашего бота. Не храните его в публичных репозиториях, не передавайте третьим лицам и не "светите" в коде, который выкладываете в открытый доступ. Компрометация токена позволит злоумышленнику полностью перехватить управление вашим ботом.

3. Шаг 2: Подготовка рабочего окружения

Перед написанием кода необходимо настроить изолированное окружение для нашего проекта. Это стандартная практика в Python-разработке, которая позволяет избежать конфликтов зависимостей между разными проектами.

1. Системные требования

Убедитесь, что на вашей системе установлен Python версии 3.8 или выше. Проверить это можно, выполнив в терминале команду:

python --version
# или python3 --version

2. Создание виртуального окружения

Мы будем использовать встроенный модуль venv для создания локальной копии интерпретатора Python и менеджера пакетов pip.

Откройте терминал в директории, где будет храниться ваш проект, и выполните следующую команду:

python -m venv venv

Эта команда создаст в вашем проекте папку venv, содержащую все необходимые файлы.

3. Активация виртуального окружения

Чтобы начать использовать окружение, его нужно активировать. Команда для активации зависит от вашей операционной системы:

Для Windows (Command Prompt или PowerShell):
```
venv\Scripts\activate
```
Для macOS / Linux (bash/zsh):
```
source venv/bin/activate
```

После успешной активации в начале строки вашего терминала появится префикс (venv). Это означает, что все последующие команды, связанные с Python и pip, будут выполняться в контексте этого изолированного окружения.

4. Установка Aiogram

Теперь, когда окружение активно, установим библиотеку aiogram и все ее зависимости одной командой:

pip install aiogram

Менеджер пакетов pip автоматически загрузит и установит последнюю стабильную версию aiogram из репозитория PyPI. На этом подготовка окружения завершена.

4. Шаг 3: Разработка кода эхо-бота

Теперь, когда окружение готово, создадим в корневой папке проекта файл main.py и разместим в нем следующий код. Ниже приведено детальное описание каждого блока.

Полный код main.py:

import asyncio
import logging

from aiogram import Bot, Dispatcher, types
from aiogram.filters.command import Command

# ВАЖНО! Вставьте сюда ваш токен, полученный от @BotFather
BOT_TOKEN = "ВАШ_ТОКЕН_ЗДЕСЬ"

# Включаем логирование, чтобы не пропустить важные сообщения
logging.basicConfig(level=logging.INFO)

# Объект бота
bot = Bot(token=BOT_TOKEN)
# Диспетчер
dp = Dispatcher()

# Хэндлер на команду /start
@dp.message(Command("start"))
async def cmd_start(message: types.Message):
    await message.answer("Привет! Я эхо-бот. Отправь мне любое сообщение, и я его повторю.")

# Хэндлер на остальные текстовые сообщения
@dp.message()
async def echo_handler(message: types.Message):
    await message.answer(f"Я получил твое сообщение: {message.text}")

# Запуск процесса поллинга новых апдейтов
async def main():
    # Удаляем вебхук и пропускаем накопившиеся входящие сообщения
    await bot.delete_webhook(drop_pending_updates=True)
    await dp.start_polling(bot)


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

Обязательно замените "ВАШ_ТОКЕН_ЗДЕСЬ" на реальный токен, который вы скопировали на предыдущем шаге.

Структурный разбор кода

a. Импорты и настройка логирования

import asyncio
import logging
from aiogram import Bot, Dispatcher, types
from aiogram.filters.command import Command

asyncio: Стандартная библиотека Python для запуска асинхронного кода.
logging: Стандартная библиотека для вывода информационных сообщений и ошибок в консоль. logging.basicConfig(level=logging.INFO) настраивает базовый уровень логирования, что полезно для отладки.
aiogram.*: Основные компоненты фреймворка:
- Bot: Класс для взаимодействия с Telegram Bot API (отправка сообщений, удаление вебхука и т.д.).
- Dispatcher: Объект, отвечающий за обработку входящих событий (апдейтов) и их маршрутизацию по соответствующим обработчикам (хэндлерам).
- types: Модуль, содержащий типы данных Telegram, такие как Message.
- Command: Фильтр, который позволяет хэндлеру реагировать только на сообщения, являющиеся командами (например, /start).

b. Инициализация объектов

BOT_TOKEN = "ВАШ_ТОКЕН_ЗДЕСЬ"
bot = Bot(token=BOT_TOKEN)
dp = Dispatcher()

Здесь мы создаем основные экземпляры: bot, который является нашим клиентом для API Telegram и требует для инициализации токен, и dp (диспетчер), который будет управлять обработкой сообщений.

c. Создание обработчиков (хэндлеров)

Хэндлер — это асинхронная функция, которая выполняется, когда Dispatcher получает соответствующее ей событие.

# Хэндлер на команду /start
@dp.message(Command("start"))
async def cmd_start(message: types.Message):
    await message.answer("Привет! Я эхо-бот. Отправь мне любое сообщение, и я его повторю.")

@dp.message(...): Это декоратор, который регистрирует функцию cmd_start в качестве обработчика сообщений.
Command("start"): Фильтр, который указывает, что этот хэндлер должен срабатывать только в том случае, если текст сообщения — это в точности команда /start.
async def cmd_start(...): Асинхронная функция, принимающая объект message типа types.Message, который содержит всю информацию о входящем сообщении.
await message.answer(...): Короткий и удобный метод для отправки ответного сообщения в тот же чат, откуда пришло исходное.

# Хэндлер на остальные текстовые сообщения
@dp.message()
async def echo_handler(message: types.Message):
    await message.answer(f"Я получил твое сообщение: {message.text}")

@dp.message(): Декоратор без фильтров означает, что этот хэндлер будет обрабатывать любые сообщения, которые не были перехвачены хэндлерами, объявленными выше. Именно поэтому его важно размещать после более специфичных, таких как обработчик команды /start.
message.text: В этом свойстве объекта message хранится текст входящего сообщения, который мы используем для формирования ответа.

d. Функция запуска и точка входа

async def main():
    await bot.delete_webhook(drop_pending_updates=True)
    await dp.start_polling(bot)

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

main(): Основная асинхронная функция, координирующая запуск бота.
await bot.delete_webhook(drop_pending_updates=True): Эта строка кода важна при разработке. Она удаляет любые ранее установленные вебхуки и указывает серверу Telegram не отправлять боту сообщения, которые скопились, пока он был выключен. Это предотвращает нежелательные срабатывания на старые команды при перезапуске скрипта.
await dp.start_polling(bot): Эта команда запускает long polling — основной режим работы бота при локальной разработке. Диспетчер начинает непрерывно опрашивать серверы Telegram на предмет новых сообщений.
if __name__ == "__main__":: Стандартная конструкция в Python, которая гарантирует, что код внутри блока будет выполнен только при прямом запуске файла main.py.
asyncio.run(main()): Запускает выполнение нашей асинхронной функции main и управляет циклом событий.

5. Шаг 4: Запуск и тестирование

После того как код написан и токен вставлен, можно приступать к первому запуску. Процесс состоит из активации скрипта и проверки его функциональности непосредственно в Telegram.

1. Запуск скрипта

Убедитесь, что вы находитесь в терминале в корневой директории вашего проекта и ваше виртуальное окружение (venv) активно.

Для запуска бота выполните следующую команду:

python main.py

Если все было сделано правильно, в консоли появятся информационные сообщения от aiogram, свидетельствующие о начале работы. Критически важно, что ошибок быть не должно, а сам скрипт не завершит свою работу, а останется активным — вы увидите мигающий курсор. Это означает, что бот успешно запустился и начал процесс получения обновлений (long polling).

Примерный вывод в консоли:

INFO:aiogram.dispatcher:Default BotPoller started
INFO:aiogram.dispatcher:Starting polling for bot id=1234567890 name='My Test Project Bot' username='@my_test_project_bot'

Не закрывайте это окно терминала. Пока скрипт запущен, ваш бот находится в сети. Чтобы его остановить, нажмите Ctrl+C.

2. Тестирование в Telegram

Теперь откройте клиент Telegram и проверьте работу бота:

Найдите своего бота по его username, который вы задали на первом шаге (например, my_test_project_bot).
Откройте с ним диалог и нажмите кнопку "Start". В ответ бот должен немедленно прислать приветственное сообщение: Привет! Я эхо-бот. Отправь мне любое сообщение, и я его повторю. Это подтверждает, что хэндлер на команду /start работает корректно.
Отправьте любое текстовое сообщение, например, Тестовое сообщение 123. Бот должен тут же ответить: Я получил твое сообщение: Тестовое сообщение 123. Это показывает, что второй хэндлер, отвечающий за обработку прочего текста, также функционирует.
Попробуйте отправить стикер, фото или любой другой тип файла. Бот никак не отреагирует на эти действия. Такое поведение ожидаемо, поскольку мы не определяли в коде обработчики для данных типов сообщений. Диспетчер просто игнорирует апдейты, для которых не найдено подходящих хэндлеров.

Поздравляем! Вы успешно создали, запустили и протестировали своего первого Telegram-бота на aiogram 3.

6. Заключение

Для закрепления материала и более глубокого понимания структуры кода предлагаем вам выполнить несколько заданий. Они помогут развить базовые навыки и научиться самостоятельно модифицировать логику бота.

Задачи для самостоятельной работы

Задание 1: Свой характер

Что нужно сделать: Измените тексты ответов вашего бота на команду /start и на обычные сообщения. Сделайте его уникальным: пусть он будет вежливым дворецким, дерзким роботом или кем-угодно еще.

Пример:

Пользователь: /start
Бот: Приветствую, сударь. Я к вашим услугам. Чем могу быть полезен?

Пользователь: расскажи анекдот
Бот: Я не был запрограммирован на юмор, сударь. Я лишь повторяю ваши фразы: расскажи анекдот

Цель: Научиться уверенно редактировать существующие хэндлеры и понимать, какая часть кода за какой ответ отвечает.

Задание 2: Новая команда /help

Что нужно сделать: По аналогии с обработчиком команды /start, добавьте новую команду /help. При вызове этой команды бот должен присылать сообщение с объяснением, что он умеет делать (например, "Я простой эхо-бот. Просто отправь мне любое сообщение, и я его тебе верну.").

Подсказка: Вам нужно будет скопировать блок хэндлера @dp.message(Command("start")), изменить в нем команду на "help" и написать новый текст для ответа.

Ожидаемый результат:

Пользователь: /help
Бот: Я простой эхо-бот. Просто отправь мне любое сообщение, и я его тебе верну.

Цель: Научиться создавать новые обработчики команд.

Задание 3: Персональное приветствие

Что нужно сделать: Усовершенствуйте команду /start. Бот должен не просто здороваться, а обращаться к пользователю по имени.

Подсказка: Имя пользователя хранится в объекте message. Получить его можно так: message.from_user.full_name. Используйте f-строку, чтобы вставить имя в ответ.

Ожидаемый результат:

Пользователь: /start
Бот: Привет, Василий Пупкин! Рад тебя видеть.

Цель: Научиться извлекать базовую информацию о пользователе из объекта message.

Задание 4: Бот-секретарь

Что нужно сделать: Измените логику эхо-хэндлера. Теперь он должен не просто повторять сообщение, а отвечать: "Ваше сообщение 'ТЕКСТ_СООБЩЕНИЯ' принято в обработку."

Подсказка: Вам снова понадобится f-строка и message.text.

Ожидаемый результат:

Пользователь: Перезвоните в 15:00
Бот: Ваше сообщение 'Перезвоните в 15:00' принято в обработку.

Цель: Закрепить навык использования данных из сообщения для формирования ответа.

Задание 5 (со звездочкой): Секретное слово*

Что нужно сделать: Модифицируйте эхо-хэндлер. Он должен работать как обычно, но если пользователь пришлет ему секретное слово (например, "котик"), бот должен отреагировать на него особенным образом. Во всех остальных случаях он работает как в задании 4.

Подсказка: Внутри функции-хэндлера echo_handler вам понадобится обычная конструкция Python if/else.

Ожидаемый результат:

Пользователь: Привет, как дела?
Бот: Ваше сообщение 'Привет, как дела?' принято в обработку.

Пользователь: котик
Бот: Мяу! Вы нашли секретное слово! ᓚᘏᗢ

Цель: Научиться добавлять простую условную логику на Python внутри асинхронных функций-обработчиков.

Анонс новых статей, полезные материалы, а так же если в процессе решения возникнут сложности, обсудить их или задать вопрос по статье можно в моём Telegram-сообществе.

Уверен, у вас все получится. Вперед, к практике!

> Вторая часть