Учебник Телеграм-боты на Python (aiogram) для начинающих

Программа курса

1. 1 Введение

   1. Что такое бот и как он общается с Telegram

      Что такое Telegram-бот, чем он отличается от человека и как программа через Bot API обменивается сообщениями с серверами Telegram.

   2. Создаём бота через BotFather

      Как зарегистрировать своего Telegram-бота через BotFather, получить токен, задать имя и юзернейм и сохранить секретный ключ в безопасности.

   3. Первый бот на Python: /start

      Пишем первого Telegram-бота на Python и aiogram 3.x: устанавливаем библиотеку, подключаем токен и отвечаем на команду /start.

   4. Как устроен Bot API: polling vs webhook

      Чем polling отличается от webhook в Telegram Bot API, как бот получает обновления и какой способ выбрать на старте, а какой — для продакшена.

2. 2 Сообщения и команды

   1. Хэндлеры сообщений и команд

      Как в aiogram 3.x устроены хэндлеры: регистрация через роутер и декораторы, фильтры Command и F, и порядок их срабатывания.

   2. Отправка текста и форматирование

      Отправляем текст из бота на aiogram: разметка HTML и MarkdownV2, жирный, курсив, ссылки и моноширинный код в сообщениях.

   3. Эхо-бот и работа с текстом

      Делаем эхо-бота на aiogram, который повторяет и преобразует текст пользователя: верхний регистр, переворот строки и подсчёт слов.

   4. Команды с аргументами

      Команды с аргументами в aiogram: разбираем /add молоко через CommandObject, парсим параметры и обрабатываем пустой ввод.

   5. Фото, файлы, стикеры, голосовые

      Как бот на aiogram принимает и отправляет фото, документы, стикеры и голосовые: file_id, answer_photo и реакция на разные типы контента.

3. 3 Кнопки и интерфейс

   1. Reply-клавиатуры

      Reply-клавиатуры в aiogram: строим кнопки через ReplyKeyboardBuilder, размечаем ряды и обрабатываем нажатия как обычный текст.

   2. Inline-кнопки и callback

      Inline-кнопки в aiogram: InlineKeyboardBuilder, callback_data, хэндлер на callback_query и обязательный ответ через answer().

   3. Меню команд и подсказки

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

   4. Редактирование и удаление сообщений

      Редактируем и удаляем сообщения бота на aiogram: edit_text, edit_reply_markup и delete для обновления карточек и интерфейсов.

4. 4 Диалоги и состояния

   1. FSM: машина состояний

      FSM в aiogram 3.x: что такое состояния, как описать StatesGroup, войти в состояние через set_state и провести пользователя по шагам диалога.

   2. Хранение состояния пользователя

      Хранилище состояний FSM в aiogram: MemoryStorage против Redis, сохранение данных через state.update_data и их чтение на следующих шагах.

   3. Валидация ввода

      Проверка пользовательского ввода в FSM-диалоге: валидация числа и текста, вежливые сообщения об ошибке и повтор шага без потери прогресса.

   4. Отмена и навигация по шагам

      Отмена диалога и навигация по шагам в FSM aiogram: команда /cancel, кнопка «Назад», сброс состояния через state.clear и возврат к предыдущему шагу.

5. 5 Данные и хранилище

   1. Зачем боту база данных

      Зачем Telegram-боту база данных: почему память исчезает после перезапуска и где хранить пользователей, настройки и историю надёжно.

   2. SQLite для бота

      Подключаем SQLite к Telegram-боту: создаём таблицу пользователей, делаем INSERT и SELECT и связываем запросы к базе с хэндлерами aiogram.

   3. Модель пользователя и настройки

      Храним профиль и настройки пользователя бота в SQLite: поля города, языка и уведомлений, чтение и обновление настроек по telegram id.

   4. Основы SQLAlchemy

      Знакомство с SQLAlchemy для бота: модель пользователя как класс, сессии и базовые операции add, get и commit вместо ручного SQL.

6. 6 Интеграции с внешним миром

   1. Запросы к внешним API (aiohttp)

      Делаем HTTP-запросы из Telegram-бота через aiohttp: асинхронный ClientSession, GET-запрос к API, разбор JSON и обработка ошибок сети.

   2. Бот-погода

      Бот-погода на aiogram и aiohttp: спрашиваем город, ходим к погодному API, разбираем температуру и описание и красиво отвечаем пользователю.

   3. Бот-переводчик и словарь

      Бот-переводчик на aiogram: отправляем текст к API перевода, получаем результат, добавляем выбор языка и обрабатываем длинный ввод.

   4. Новостной бот: парсинг и отправка

      Новостной бот на Python: получаем ленту через API или RSS, разбираем заголовки и ссылки и отправляем подборку новостей в Telegram.

   5. Работа с изображениями

      Работа с картинками в боте: скачиваем фото пользователя, обрабатываем через Pillow и отправляем обратно изменённое изображение.

7. 7 Полезные паттерны

   1. Рассылки и уведомления

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

   2. Планировщик задач: напоминалки

      Напоминания в боте через APScheduler: планируем отложенные и повторяющиеся задачи и отправляем сообщение пользователю в нужное время.

   3. Throttling и анти-спам

      Throttling в aiogram через middleware: ограничиваем частоту сообщений от пользователя, защищаем бота от спама и вежливо просим не частить.

   4. Логирование и обработка ошибок

      Логирование и обработка ошибок в боте на aiogram: модуль logging, глобальный обработчик ошибок и понятный ответ пользователю при сбое.

8. 8 Группы и администрирование

   1. Бот в группах: права и события

      Бот в группах Telegram: режим приватности, права администратора и обработка событий входа и выхода участников через ChatMemberUpdated.

   2. Модерация: мут, бан, фильтры

      Модерация в Telegram-боте: мут и бан через restrict и ban_chat_member, фильтр запрещённых слов и удаление нарушающих сообщений.

   3. Капча для новых участников

      Капча для новичков в группе на aiogram: ограничиваем нового участника, даём проверку кнопкой и снимаем ограничения после прохождения.

   4. Админ-панель и роли

      Админ-панель бота: список админов из настроек, фильтр доступа к командам по роли и закрытое меню управления для администраторов.

9. 9 Деплой

   1. Переменные окружения и секреты

      Храним токен и секреты бота правильно: переменные окружения, файл .env, python-dotenv и почему секреты нельзя коммитить в репозиторий.

   2. Webhook и хостинг

      Переводим бота с polling на webhook: настраиваем set_webhook, поднимаем aiohttp-сервер и понимаем, зачем нужны HTTPS и публичный адрес.

   3. Деплой на сервер (VPS) и Docker

      Деплой Telegram-бота на VPS: установка зависимостей, запуск через systemd, упаковка в Docker и Dockerfile для стабильной работы 24/7.

   4. Бесплатные хостинги и мониторинг

      Где бесплатно держать Telegram-бота и как следить за ним: варианты хостингов, авто-перезапуск, логи и оповещения о падении бота.

10. 10 Финал

    1. Финальный проект: бот-помощник

       Собираем финальный проект — бота-помощника на aiogram: команды, кнопки, FSM, база данных и внешний API в одном работающем боте.

    2. Монетизация, лимиты и что дальше

       Как заработать на Telegram-боте и не упереться в лимиты: способы монетизации, ограничения Bot API и пути развития после курса.