Телеграмм бот на 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-сообществе.

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

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