Telegram-боты на Python с нуля

Введение: как устроены Telegram-боты и что нужно для старта

Что такое Telegram-бот

Telegram-бот — это специальный аккаунт в Telegram, который умеет автоматически отвечать пользователям, принимать команды, отправлять сообщения, кнопки, файлы и выполнять полезные действия (например, искать информацию, вести заметки, принимать заявки).

Ключевая идея простая:

Пользователь пишет боту в Telegram

Telegram доставляет сообщение вашему коду

Ваш код решает, что ответить, и отправляет ответ обратно через Telegram

Бот не “живёт внутри Telegram”. Он работает в вашей программе (на вашем компьютере или на сервере), а Telegram выступает как “почтальон”, который передаёт сообщения туда и обратно.

!Схема: как сообщение проходит от пользователя до вашего кода и возвращается обратно

Из чего состоит бот: основные элементы

Аккаунт бота

Это “профиль” бота в Telegram. Его создают через специального бота Telegram — BotFather. У аккаунта бота есть:

Имя и username (например, @my_first_bot)

Уникальный токен доступа (секретная строка)

Токен

Токен — это секретный ключ, который позволяет вашей программе управлять ботом.

Важно:

Токен нельзя публиковать и отправлять посторонним

Если токен утек — его нужно заменить (перевыпустить) через BotFather

Telegram Bot API

Bot API — это набор правил и методов, с помощью которых программы общаются с Telegram и управляют ботом.

Примеры того, что ваш код может “попросить” у Telegram через Bot API:

Отправить сообщение пользователю

Узнать, что пользователь написал

Отправить клавиатуру с кнопками

Принять файл

Официальная документация:

Telegram Bot API

Боты в Telegram (обзор)

Ваш код на Python

Ваш Python-код делает две вещи:

Получает новые сообщения и события (например, “пользователь нажал кнопку”)

Выбирает логику ответа (например, “если написали /start — поздороваться”)

Пока вы не знаете Python — это нормально. В курсе мы будем идти от установки и самых базовых конструкций к полноценному боту.

Как Telegram “доставляет” сообщения боту

Есть два основных способа, как ваш код получает новые сообщения от Telegram.

Polling

Polling — это когда ваша программа сама регулярно спрашивает у Telegram: “Есть ли новые сообщения?”

Плюсы:

Легко запустить на своём компьютере

Хорошо подходит для обучения и первых ботов

Минусы:

Программа должна постоянно работать (пока она выключена — бот “не отвечает”)

Webhook

Webhook — это когда Telegram сам отправляет сообщения на ваш сервер по специальному адресу.

Плюсы:

Удобно для постоянной работы на сервере

Telegram сам “стучится” к вам, когда есть новое событие

Минусы:

Нужно развернуть сервер и настроить доступ из интернета

Обычно сложнее на старте

В этом курсе для первых шагов мы будем использовать подход, который проще начать и проверить (как правило, это polling), а к webhook перейдём позже, когда появится база.

Что нужно установить и подготовить

Telegram

Нужно иметь обычный аккаунт Telegram (установленное приложение) — чтобы создать бота и тестировать его.

Python

Python — язык, на котором мы будем писать бота.

Сайт Python: Python.org

Важная мысль: Python — это не “приложение для ботов”, а общий язык программирования. Telegram-бот — это просто один из видов программ.

Редактор кода

Редактор — это программа, где вы пишете код.

Популярный вариант для новичков:

Visual Studio Code

Установка библиотек

Чтобы не писать “общение с Telegram” с нуля, обычно используют библиотеку — готовый набор инструментов.

Два распространённых варианта (оба популярны, но разные):

python-telegram-bot (документация)

aiogram (документация)

В курсе мы выберем одну библиотеку и будем последовательно работать с ней, но важно понимать общий принцип: библиотека помогает удобно вызывать Bot API.

Виртуальное окружение

Виртуальное окружение — это изолированная “папка с зависимостями”, чтобы проекты не мешали друг другу.

Официальная документация:

venv — виртуальные окружения Python

На первых шагах мы сделаем окружение вместе, пошагово.

Как выглядит путь от идеи до работающего бота

Ниже общий маршрут, который мы пройдём в курсе.

Создать бота в BotFather и получить токен

Установить Python и редактор кода

Создать проект и виртуальное окружение

Установить библиотеку для работы с Telegram

Написать простой сценарий: бот отвечает на команду и на текст

Добавить кнопки, состояния диалога и полезную логику

Научиться запускать бота так, чтобы он работал постоянно (например, на сервере)

Безопасность и правила хорошего старта

Чтобы не столкнуться с проблемами уже в начале, запомните несколько правил.

Никогда не публикуйте токен бота (например, в публичном репозитории)

Храните секреты отдельно от кода (мы научимся делать это аккуратно)

Не доверяйте “готовым” ботам/скриптам из случайных источников, если не понимаете, что внутри

Начинайте с маленьких шагов: сначала ответ на /start, потом один простой сценарий, и только потом усложнение

Что будет в следующей статье

Дальше мы перейдём к практическому старту: создадим бота через BotFather, разберём, где взять токен, и подготовим рабочее окружение на компьютере. После этого у вас появится первый “живой” бот, которому можно написать в Telegram.

Основы Python для будущего бота: синтаксис, типы, функции

В прошлой статье мы разобрали, как Telegram доставляет сообщения вашему коду и почему бот — это обычная программа, которая общается с Telegram через API.

Теперь нам нужна база Python, чтобы уже в следующих шагах написать первого бота (например, обработчик /start и ответы на текст).

Как «выглядит» Python-код и почему важны отступы

Python читается сверху вниз. Блоки кода (например, внутри if или def) выделяются отступами, а не фигурными скобками.

Правила, которые спасают новичка от ошибок:

В одном проекте используйте один стиль отступов: обычно 4 пробела.

Не смешивайте табы и пробелы.

Если Python «ругается» на отступы, проверьте, где начался и где закончился блок.

Переменные и присваивание

Переменная — это имя, которое указывает на значение.

Полезные правила именования:

Имя должно описывать смысл: user_name лучше, чем x.

В Python обычно используют snake_case: message_text, chat_id.

Нельзя начинать имя с цифры.

Базовые типы данных

В ботах вы постоянно будете работать с текстом, числами, логикой «да/нет» и пустыми значениями.

!Шпаргалка по основным типам данных Python, которые чаще всего встречаются в коде бота

Числа: int и float

int — целые числа: 1, 0, -10

float — дробные: 3.14, 0.5

Строки: str

Строка — это текст.

Частые операции со строками:

Склеить строки: a + b

Узнать длину: len(text)

Привести к нижнему регистру: text.lower()

#### Форматирование строк через f-строки

f-строки удобны, когда нужно подставить переменные в текст ответа бота.

Логика: bool

bool бывает двух значений:

True — истина

False — ложь

Обычно получается из сравнений:

Пустое значение: None

None означает «значения нет».

В ботах None часто встречается как «пока не задано» или «не нашли».

Коллекции: как хранить много значений

Список: list

Список — упорядоченная коллекция.

Что важно:

Индексация начинается с 0: commands[0] это '/start'.

Добавление в конец: commands.append('/settings').

Длина списка: len(commands).

Словарь: dict

Словарь хранит пары «ключ → значение». Это очень похоже на то, как вы будете хранить настройки пользователя или временное состояние диалога.

Полезные моменты:

Ключи чаще всего строки: 'name', 'state', 'lang'.

Обращение к отсутствующему ключу через user['age'] вызовет ошибку.

Более безопасный способ получить значение: user.get('age') вернёт None, если ключа нет.

Таблица: что когда использовать

| Что нужно сделать | Подходит | Почему | |---|---|---| | Хранить набор команд по порядку | list | Есть порядок и индексы | | Хранить данные пользователя по полям | dict | Доступ по ключам 'name', 'id' | | Хранить одну «вещь» | переменная | Проще и читаемее |

Условия: как принимать решения

Бот постоянно принимает решения: это команда /start или обычный текст? Пользователь ввёл число или нет?

Операторы сравнения:

== равно

!= не равно

> больше, < меньше, >= больше или равно, <= меньше или равно

Логические операторы:

and — и

or — или

not — не

Циклы: повторяем действия

for: пройти по коллекции

while: повторять, пока условие истинно

while полезен реже в простых ботах, но знать его важно.

Управление циклом:

break — выйти из цикла

continue — перейти к следующей итерации

Функции: как не писать одно и то же много раз

Функция — это именованный кусок кода, который можно вызывать много раз.

Зачем функции в боте

Чтобы разнести логику по маленьким понятным частям.

Чтобы обработчики сообщений были короткими и читабельными.

Чтобы повторно использовать код (например, форматировать ответы).

Как объявить и вызвать функцию

Ключевые слова:

def — начало объявления функции.

return — вернуть результат наружу.

Если return не написан, функция вернёт None.

Параметры по умолчанию

Именованные аргументы

Вы можете вызывать функцию, явно указывая, что куда передаёте:

Ошибки и исключения: что будет, если «что-то пошло не так»

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

Примеры частых ошибок новичка:

SyntaxError — опечатка в синтаксисе.

IndentationError — неверные отступы.

TypeError — попытка сделать операцию с неподходящими типами.

KeyError — обращение к отсутствующему ключу словаря через dict[key].

Чтобы аккуратно обрабатывать «опасные места», используют try/except.

В боте это пригодится, когда пользователь вводит произвольный текст, а вы ожидаете число, дату и т.д.

Как это связано с Telegram-ботом

Когда мы начнём писать код бота, у вас появятся сущности вроде:

message_text (строка str) — что написал пользователь

chat_id (число int) — куда отвечать

user_data (словарь dict) — временные данные о пользователе

функции-обработчики — чтобы реагировать на команды и сообщения

То есть всё, что вы изучили здесь, напрямую превращается в «кирпичики» логики бота.

Что почитать в официальной документации (по желанию)

Учебник Python (официальная документация)

Встроенные типы данных

Определение функций

В следующей части мы перейдём к практике: подготовим окружение и напишем самый простой каркас бота, который уже сможет отвечать в Telegram.

Среда разработки: установка Python, venv, pip, Git и структура проекта

В прошлых статьях мы разобрали, что такое Telegram-бот и какие базовые конструкции Python вам понадобятся (переменные, типы, функции, условия).

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

Эта статья — про инструменты, без которых разработка бота быстро превращается в хаос.

Что мы настроим и зачем

Python — интерпретатор, который запускает ваш код.

pip — менеджер пакетов Python: устанавливает библиотеки (например, для работы с Telegram).

venv — виртуальное окружение: изолирует зависимости конкретного проекта.

Git — контроль версий: сохраняет историю изменений проекта и помогает не потерять рабочий код.

Структура проекта — понятные папки и файлы, чтобы проект было легко развивать.

Установка Python

Какую версию ставить

Рекомендуемый вариант для обучения и первых ботов: Python 3.11 или 3.12.

Почему важно именно Python 3: многие современные библиотеки (в том числе для Telegram-ботов) не поддерживают Python 2.

Установка (общие принципы)

Скачайте установщик Python с официального сайта: Python Downloads

Установите Python.

Проверьте, что Python доступен из терминала.

Важный момент для Windows

При установке на Windows обычно есть галочка Add Python to PATH. Если вы видите её — включите. Тогда команда python будет работать в терминале.

Проверка установки

Откройте терминал:

Windows: PowerShell или Terminal

macOS: Terminal

Linux: любой терминал

Проверьте версию:

Если python не находится, попробуйте:

Ожидаемый результат — что-то вроде Python 3.12.x.

pip: установка библиотек

pip — это инструмент, который скачивает и устанавливает библиотеки.

Проверка pip:

Почему часто используют именно python -m pip, а не просто pip:

так вы точно вызываете pip, привязанный к этому Python;

меньше путаницы, если у вас несколько версий Python.

Пример установки пакета:

Позже вы этой же командой будете ставить библиотеку для Telegram-бота.

venv: виртуальное окружение (обязательно для проектов)

Зачем нужно виртуальное окружение

Представьте, что у вас два проекта:

проект A требует библиотеку версии 1.0

проект B требует ту же библиотеку версии 2.0

Если ставить всё “в систему”, проекты начинают конфликтовать.

venv создаёт отдельную папку окружения для проекта — и зависимости живут внутри неё.

Официальная документация: venv — Creation of virtual environments

Создание окружения

Перейдите в папку, где будет проект, и создайте окружение:

Здесь .venv — имя папки окружения. Часто используют именно такое имя.

Активация окружения

После активации:

команды python и pip будут относиться к окружению проекта;

пакеты установятся внутрь .venv, а не в систему.

Команды активации:

| ОС | Команда | |---|---| | Windows (PowerShell) | .venv\Scripts\Activate.ps1 | | Windows (cmd) | .venv\Scripts\activate.bat | | macOS / Linux | source .venv/bin/activate |

Чтобы выйти из окружения:

Проверка: куда смотрит Python

После активации можно проверить путь к Python:

Если окружение активировано, путь будет указывать на папку .venv.

Фиксация зависимостей: requirements.txt

Чтобы другой человек (или вы сами через неделю) могли быстро восстановить зависимости, принято сохранять список пакетов.

Сгенерировать список установленных пакетов:

Установить зависимости по файлу:

Важно понимать смысл:

requirements.txt — это список библиотек и их версий

.venv — это “сборка” окружения, которую обычно не хранят в репозитории

Git: контроль версий

Зачем нужен Git даже новичку

Git помогает:

сохранить историю изменений;

вернуться к рабочей версии, если “сломали всё”;

переносить проект на другой компьютер;

позже — работать с GitHub и деплоить бота.

Установка Git

Официальный сайт: Git

Проверка установки:

Инициализация репозитория

В корне проекта:

Настройка имени и email (один раз)

Что такое коммит (очень кратко)

Коммит — это сохранённый снимок состояния проекта с комментарием.

Типичный цикл:

.gitignore: что не надо добавлять в репозиторий

В репозиторий обычно не добавляют:

виртуальное окружение .venv/;

временные файлы редактора;

кэш Python.

Создайте файл .gitignore в корне проекта и добавьте:

Здесь .env — популярный файл для секретов (например, токена бота). Мы к нему вернёмся позже, когда будем запускать реального бота.

Рекомендуемая структура проекта для первого Telegram-бота

На старте важно не усложнять. Ниже — простая структура, которая подходит для обучения и небольших ботов.

!Схема структуры проекта и где какие файлы лежат

Пример структуры:

Что здесь что:

README.md — кратко: что делает бот и как запустить.

.gitignore — список того, что Git должен игнорировать.

requirements.txt — зависимости проекта.

src/ — исходный код.

src/app.py — точка входа: запуск бота.

src/config.py — конфигурация (позже: токен, настройки).

data/ — данные проекта (если понадобятся: файлы, простые базы, шаблоны).

Почему код лучше держать в src/

Так проще:

отделять исходный код от файлов проекта;

избегать путаницы, когда рядом лежат заметки, данные, эксперименты;

расти до более серьёзной структуры, если бот станет больше.

Минимальная проверка, что всё работает

Сделайте файл src/app.py:

Запуск из корня проекта:

Если вы видите сообщение — значит:

Python установлен;

проект запускается;

терминал и рабочая папка выбраны правильно.

Частые проблемы и как их распознать

Команда python не находится

Обычно это означает:

Python не добавлен в PATH (часто на Windows);

вы используете python, а нужно python3 (часто на macOS/Linux).

Пакеты поставились “не туда”

Частый сценарий: окружение не активировали и установили пакет в системный Python.

Решение:

активировать .venv;

повторить python -m pip install ... уже внутри окружения.

Путаются разные окружения

Привычка, которая помогает:

на каждый проект — своё окружение .venv;

ставить пакеты только после активации;

проверять python -c "import sys; print(sys.executable)".

Что будет дальше

В следующей части мы возьмём эту среду разработки и сделаем первый “живой” шаг к Telegram:

установим библиотеку для бота через pip;

создадим бота в BotFather (если ещё не сделали);

напишем минимальный код, который отвечает на /start.

Первый бот: BotFather, токен, команды и обработка сообщений

В прошлых статьях вы узнали, как устроены Telegram-боты, выучили базовые конструкции Python и настроили среду разработки (Python, venv, pip, Git и структуру проекта).

Теперь соберём это в первого живого бота, которому можно написать в Telegram и получить ответ.

!Общая схема: как сообщение проходит через Telegram к вашему коду и возвращается обратно

Что вы сделаете после этой статьи

Создадите бота через BotFather и получите токен

Настроите команды бота, которые будут видны в интерфейсе Telegram

Установите библиотеку для работы с Telegram на Python

Напишете код, который обрабатывает /start, /help и обычные текстовые сообщения

Запустите бота через polling и протестируете его

Шаг первый: создаём бота в BotFather

BotFather — официальный бот Telegram, через которого создаются и настраиваются другие боты.

Официальная документация Telegram (раздел про BotFather): BottFather в документации Telegram

Создание бота

Откройте Telegram и найдите пользователя @BotFather.

Нажмите Start (или напишите /start).

Отправьте команду /newbot.

BotFather попросит:

1. Имя бота (можно русское, это “отображаемое имя”). 2. Username (должен заканчиваться на bot, например my_first_course_bot).

В ответ BotFather выдаст токен.

Что такое токен и почему его нельзя показывать

Токен — это секретный ключ, который даёт вашей программе право управлять ботом.

Правила безопасности:

Не публикуйте токен в чатах, на скриншотах, в репозитории GitHub

Не коммитьте токен в Git

Если токен утёк, перевыпустите его через BotFather командой /revoke (она выдаст новый токен и старый перестанет работать)

Шаг второй: задаём команды бота (чтобы они отображались в Telegram)

Команды — это подсказки, которые Telegram показывает пользователю при вводе /.

Есть два варианта:

Настроить команды через BotFather

Обрабатывать команды в коде (мы это тоже сделаем)

Настройка команд через BotFather

Откройте @BotFather.

Отправьте команду /setcommands.

Выберите вашего бота.

Отправьте список команд в формате:

Документация Telegram про команды: Команды бота в документации Telegram

Важно понимать: настройка команд в BotFather не добавляет “логику” сама по себе. Логику вы пишете в Python, а BotFather лишь помогает Telegram показывать пользователю список доступных команд.

Шаг третий: ставим библиотеку и готовим проект

Чтобы не работать с Bot API “вручную”, мы используем библиотеку python-telegram-bot.

Документация библиотеки: python-telegram-bot Documentation

Установка зависимостей

Дальше предполагается, что вы уже создали проект и виртуальное окружение, как в предыдущей статье.

Активируйте виртуальное окружение .venv.

Установите пакеты:

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

Обновляем requirements.txt

После установки зафиксируйте зависимости:

Шаг четвёртый: храним токен в .env и читаем его из кода

В корне проекта создайте файл .env:

Проверьте, что .env уже добавлен в .gitignore (в предыдущей статье мы это делали). Если нет — добавьте строку:

Файл src/config.py

Создайте src/config.py:

Что здесь происходит:

load_dotenv() загружает переменные из .env

os.getenv("BOT_TOKEN") читает значение

если токена нет, мы явно останавливаем программу с понятной ошибкой

Шаг пятый: пишем код бота с обработчиками

В python-telegram-bot вы обычно создаёте приложение и добавляете handlers (обработчики):

CommandHandler для команд вроде /start

MessageHandler для обычного текста

Файл src/app.py

Создайте src/app.py:

Как это читать новичку

ApplicationBuilder().token(BOT_TOKEN).build() создаёт приложение и “подключает” токен

add_handler(...) добавляет правила, какие сообщения какой функции отдать

CommandHandler("start", start) означает: команда /start вызывает функцию start

MessageHandler(filters.TEXT & ~filters.COMMAND, echo) означает: обычный текст (но не команда) вызывает echo

run_polling() запускает бесконечный цикл: приложение периодически спрашивает Telegram о новых событиях

Шаг шестой: запускаем и тестируем

Запускайте из корня проекта:

Дальше:

Найдите вашего бота в Telegram по username

Нажмите Start или отправьте /start

Проверьте:

1. /help отвечает подсказкой 2. /about отвечает описанием 3. Любой текст бот повторяет

Если всё получилось — поздравляю: это ваш первый работающий бот.

Частые проблемы и быстрые решения

Бот “молчит”

Обычно причина одна из этих:

Программа не запущена (polling работает только пока ваш код запущен)

Вы запустили не тот файл или не из той папки

Токен неверный или с пробелами

Ошибка про BOT_TOKEN не найден

Проверьте:

файл .env лежит в корне проекта (там же, где requirements.txt)

строка написана как BOT_TOKEN=... без кавычек

вы действительно вставили токен от BotFather

ModuleNotFoundError: No module named ...

Почти всегда это означает, что:

не активировано окружение .venv, или

пакет не установлен в это окружение

Решение: активируйте .venv и выполните установку ещё раз через python -m pip install ....

Что будет дальше

Дальше вы начнёте делать бота более “похожим на реального”:

кнопки (клавиатуры)

хранение простого состояния диалога

обработка разных сценариев (не только “эхо”)

Но фундамент уже есть: BotFather, токен, команды и обработчики сообщений.

Логика бота: состояния, кнопки, формы и обработка ошибок

В прошлой статье вы запустили первого бота на python-telegram-bot: команды (/start, /help) и простой обработчик текста.

Следующий шаг — сделать бота похожим на реального: чтобы он вёл диалог по шагам, показывал кнопки, собирал данные как форму и не падал от неожиданных сообщений.

!Диаграмма показывает, как бот переходит между состояниями диалога

Зачем боту нужны состояния

Если бот должен задать несколько вопросов подряд, он должен помнить на каком шаге находится пользователь.

Пример сценария:

Пользователь нажал Заполнить анкету

Бот спрашивает имя

Пользователь вводит имя

Бот спрашивает возраст

Пользователь вводит возраст

Бот подтверждает данные

Без состояния бот не понимает, что означает сообщение пользователя: это имя? возраст? ответ на подтверждение?

В python-telegram-bot для таких сценариев чаще всего используют ConversationHandler.

Полезная документация:

ConversationHandler (python-telegram-bot)

Где хранить данные пользователя во время диалога

Пока пользователь проходит форму, вам нужно временно складывать ответы. Для этого удобно использовать context.user_data.

context.user_data — словарь (dict) с данными конкретного пользователя

данные живут в памяти, пока работает ваша программа

при перезапуске бота эти данные пропадут (позже в курсе можно заменить на базу данных)

Документация:

CallbackContext.user_data (python-telegram-bot)

Кнопки в Telegram: какие бывают и чем отличаются

В Telegram есть два основных типа кнопок, и это важно не перепутать.

Reply-клавиатура

ReplyKeyboardMarkup — это клавиатура вместо клавиатуры телефона. При нажатии кнопки в чат отправляется обычный текст.

Когда подходит:

меню простых действий: Анкета, Помощь, Отмена

подсказки для новичков

Документация:

ReplyKeyboardMarkup (python-telegram-bot)

Inline-кнопки

InlineKeyboardMarkup — кнопки прямо под сообщением. При нажатии не отправляется текст, а приходит событие CallbackQuery с данными callback_data.

Когда подходит:

подтверждения: Да/Нет

переключатели, выбор вариантов

управление сообщением (например, обновить текст)

Документация:

InlineKeyboardMarkup (python-telegram-bot)

CallbackQuery (Telegram Bot API)

!Визуально сравниваем два типа кнопок

Делаем форму через ConversationHandler

Ниже — пример анкеты:

стартуем из меню

спрашиваем имя

спрашиваем возраст

подтверждаем данные inline-кнопками

поддерживаем отмену /cancel и кнопкой

Подготовка: состояния и клавиатуры

Состояния удобно хранить как числа или строки. Часто используют range(...).

Создайте (или обновите) src/app.py и добавьте логику.

Что здесь важно:

MENU, ASK_NAME, ASK_AGE, CONFIRM — наши шаги диалога

ReplyKeyboardMarkup — меню кнопок снизу

InlineKeyboardMarkup — подтверждение под сообщением

Команда start: показываем меню и входим в диалог

Обратите внимание на return MENU: обработчик сообщает ConversationHandler, в каком состоянии мы теперь находимся.

Меню: выбираем, что делать дальше

Что делает ReplyKeyboardRemove():

убирает reply-клавиатуру

удобно, когда вы ожидаете ввод текста (например, имя)

Шаг имени: сохраняем ответ

Здесь мы сохраняем данные в context.user_data.

Шаг возраста: проверяем и готовим подтверждение

Что мы сделали:

int(raw) может сломаться, если пользователь введёт текст, поэтому используем try/except

добавили простую валидацию диапазона

предложили подтвердить данные inline-кнопками

Подтверждение: обрабатываем CallbackQuery

Inline-кнопки не приходят как обычное сообщение, поэтому нужен CallbackQueryHandler.

Почему важно await query.answer():

Telegram ожидает, что вы подтвердите обработку нажатия

иначе у пользователя может крутиться индикатор загрузки

Отмена: корректно выходим из диалога

Собираем ConversationHandler и запускаем

В main() создаём ConversationHandler, описываем состояния и добавляем в приложение.

Документация по CallbackQueryHandler:

CallbackQueryHandler (python-telegram-bot)

Обработка ошибок: чтобы бот не падал и было понятно, что случилось

Ошибки в боте будут всегда: нестабильная сеть, неожиданные типы сообщений, ошибки в логике. Ваша цель — не допускать ситуации, когда бот молча ломается.

Два уровня защиты

Локально, рядом с опасным местом

- например, int(raw) внутри try/except

Глобально, на уровне приложения

- логирование исключений и сообщение пользователю

Локальная обработка: ожидаем плохой ввод

Мы уже применили это в ask_age():

пользователь может написать "пятнадцать"

int() вызовет ValueError

мы ловим исключение и просим ввести снова

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

Глобальный обработчик ошибок

В python-telegram-bot можно добавить error handler, который сработает при необработанном исключении.

Документация:

Error handling (python-telegram-bot)

Пример:

И подключение в main():

Что это даёт:

вы видите traceback в логах

пользователь получает понятное сообщение вместо тишины

Типичные ошибки новичка в диалогах и как их избегать

Смешали reply-кнопки и inline-кнопки

- reply-кнопка отправляет текст, inline-кнопка вызывает CallbackQuery

Забыли вернуть состояние

- если обработчик не возвращает состояние, диалог может вести себя неожиданно

Не ответили на callback

- без query.answer() Telegram может показывать “загрузку”

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

- токен должен быть в .env, как вы сделали раньше

Ждёте текст, а пользователь прислал стикер

- ваши фильтры (filters.TEXT) должны явно ограничивать, что вы обрабатываете

Что дальше по курсу

Теперь у вас есть главный инструмент для логики: состояния диалога, кнопки и форма с валидацией.

Следующие логичные шаги после этой темы:

сделать несколько независимых сценариев (не одну анкету)

добавить хранение данных (файл, SQLite, внешняя база)

научиться запускать бота постоянно (сервер и webhook, когда будете готовы)

Данные и интеграции: файлы, SQLite, HTTP-запросы и внешние API

В предыдущих статьях вы:

создали первого Telegram-бота и научились обрабатывать команды и текст;

сделали диалог с состояниями через ConversationHandler, добавили кнопки и обработку ошибок;

временно хранили ответы пользователя в context.user_data.

Теперь сделаем следующий шаг к реальному боту: научим его

сохранять данные между перезапусками (файлы и SQLite);

получать данные из интернета (HTTP-запросы);

интегрироваться с внешними API и аккуратно обрабатывать сбои.

!Как данные и запросы проходят через бота

Зачем вообще хранить данные

Если бот живёт только в памяти (например, в context.user_data), то при перезапуске программы:

всё забывается;

нельзя сделать историю запросов;

нельзя сделать список пользователей, статистику, избранное.

Хранение данных даёт боту “память”. А интеграции с API дают “знания” извне: погода, курсы валют, расписания, поиск и так далее.

Варианты хранения данных: что выбрать новичку

Ниже два самых доступных варианта для старта.

| Вариант | Когда подходит | Плюсы | Минусы | |---|---|---|---| | Файлы (JSON/CSV) | Очень маленький проект, простые данные | Просто, без установки | Сложнее с параллельным доступом, неудобно искать и обновлять | | SQLite | Почти любой учебный и небольшой “реальный” бот | Надёжно, запросы, таблицы, работает “из коробки” | Нужно понять базовые идеи таблиц и запросов |

Рекомендация для курса: файлы полезно понять, но для “памяти” бота лучше довольно быстро перейти на SQLite.

Файлы: JSON как простая база для маленьких данных

Что такое JSON

JSON — это текстовый формат, похожий на словари и списки Python.

в Python: dict и list

в файле: текст, который можно сохранить и прочитать

Документация Python:

Модуль json

Пример: сохраняем анкеты в data/forms.json

Структура проекта (как мы делали ранее):

Сделаем модуль src/storage_json.py.

Что важно:

Path("data") делает путь понятным и переносимым между ОС.

ensure_data_dir() создаёт папку, если её ещё нет.

json.dump(..., ensure_ascii=False) сохраняет русский текст нормально.

Как использовать в боте

Например, в момент подтверждения анкеты вы можете записать:

Ограничения файлового подхода

Файлы удобны для обучения, но быстро начинают мешать:

обновлять запись неудобно (нужно прочитать всё, изменить, записать обратно);

при одновременной записи можно испортить файл;

поиск и сортировка делаются вручную.

Поэтому дальше — SQLite.

SQLite: база данных “в одном файле”

SQLite — это база данных, которая хранится в одном файле (например, data/bot.db). Она не требует отдельного сервера и подходит для маленьких и средних проектов.

Документация:

Модуль sqlite3

Основные термины простыми словами

таблица — как “лист” с данными

строка — одна запись (например, анкета одного пользователя)

колонки — поля (например, name, age)

SQL-запрос — команда базе: создать таблицу, добавить запись, найти запись

Создаём модуль хранения src/storage_sqlite.py

Сделаем три задачи:

создать таблицу при запуске;

сохранить анкету;

получить анкету по telegram_id.

Ключевые моменты, которые здесь важно понять:

data/bot.db — файл базы.

CREATE TABLE IF NOT EXISTS безопасно: создаст таблицу, если её ещё нет.

PRIMARY KEY означает, что telegram_id уникален.

? в SQL — это плейсхолдер для параметров.

параметры передаются отдельным кортежем (telegram_id,).

Почему параметры через ? — это обязательно

Так вы:

избегаете ошибок с кавычками;

защищаетесь от SQL-инъекций;

делаете код проще.

Подключаем SQLite к вашему диалогу анкеты

Если вы делали анкету из прошлой статьи, то самое логичное место для сохранения — ветка подтверждения confirm_yes.

Пример идеи (фрагмент), где вы сохраняете анкету в базу:

И в обработчике подтверждения:

Теперь анкета не исчезнет после перезапуска.

Команда: показать сохранённую анкету

Добавим команду /myform.

И подключение:

HTTP-запросы: как бот получает данные из интернета

Что такое HTTP-запрос

Когда вы обращаетесь к внешнему API, ваш бот делает запрос по URL.

GET — получить данные

POST — отправить данные (часто: создать что-то на сервисе)

Ответ обычно приходит в JSON.

Чтобы запросы не “замораживали” бота, важно:

ставить таймаут;

обрабатывать ошибки сети;

не делать слишком много запросов подряд.

Почему в асинхронном боте важен асинхронный HTTP

python-telegram-bot в наших примерах работает в async-стиле. Если вы используете синхронные запросы, вы рискуете блокировать обработку сообщений.

Хороший вариант: библиотека httpx, у неё есть AsyncClient.

Документация:

HTTPX

Установка:

Пример интеграции с внешним API: погода через Open-Meteo

Сервис Open-Meteo удобен для обучения тем, что у него есть бесплатные запросы без ключа.

Документация:

Open-Meteo API

Open-Meteo Geocoding API

Идея сценария:

пользователь пишет /weather Москва

бот находит координаты города через геокодинг

бот запрашивает текущую температуру

бот отвечает

Шаг: модуль src/weather_api.py

Здесь важно:

timeout=10.0 — чтобы бот не завис надолго.

raise_for_status() — чтобы 4xx/5xx превращались в исключение, которое можно обработать.

Шаг: обработчик команды /weather

И подключение в main():

Как аккуратно работать с внешними API

Не доверяйте данным “снаружи”

API может:

вернуть неожиданный JSON;

поменять поля;

временно упасть;

вернуть пустой список.

Поэтому ваш код должен быть устойчивым:

проверяйте наличие ключей через .get()

готовьтесь к None

оборачивайте сетевые вызовы в try/except

Таймауты, лимиты и “слишком много запросов”

Практика для ботов:

ставьте таймаут (например, 5–15 секунд)

не делайте 3–5 запросов, если можно сделать 1

при ошибке показывайте пользователю понятный текст

Если сервис вернул лимит (часто это 429 Too Many Requests), разумная реакция:

сказать пользователю “попробуйте позже”

не пытаться “долбить” API бесконечно

Где хранить ключи API и другие секреты

Как и токен бота, ключи внешних сервисов нельзя хранить прямо в коде.

Правильный подход:

хранить их в .env

читать через os.getenv() в config.py

Это тот же принцип, который вы уже применили для BOT_TOKEN.

Документация:

python-dotenv

Что вы умеете после этой статьи

Теперь вы можете собрать бота, который:

ведёт диалог и собирает данные (как в прошлой статье);

сохраняет результаты в файл или в SQLite;

достаёт сохранённые данные по команде;

делает HTTP-запросы к внешним API и показывает пользователю результат;

не падает от сетевых ошибок и непредсказуемых ответов.

Это фундамент для большинства “полезных” Telegram-ботов: учёт заявок, заметки, поиск информации, уведомления, мини-CRM.

Запуск в продакшн: деплой, вебхуки/поллинг, безопасность и мониторинг

В прошлых частях курса вы написали бота на python-telegram-bot, добавили диалоги, кнопки, обработку ошибок, а также научились хранить данные (файлы и SQLite) и ходить во внешние API.

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

Эта статья про продакшн (боевую эксплуатацию): деплой, выбор между webhook и polling, безопасность и мониторинг.

!Сравнение потоков событий для polling и webhook

Что значит «в продакшн» для Telegram-бота

В учебном режиме вы запускаете app.run_polling() на своём компьютере. В продакшне обычно требуется следующее:

Постоянная работа: бот отвечает 24/7.

Автозапуск: после перезагрузки сервера бот поднимается сам.

Управляемые обновления: вы можете обновить код без хаоса.

Секреты вне кода: токены и ключи API не в репозитории.

Логи и мониторинг: вы видите ошибки и понимаете, что происходит.

Polling и Webhook: что выбрать

Polling

Polling означает, что бот сам регулярно запрашивает обновления у Telegram методом getUpdates.

Когда polling хорош:

вы хотите самый простой деплой;

бот небольшой или учебный;

у вас нет домена и HTTPS;

вы деплоите на VPS и хотите минимум инфраструктуры.

Минусы polling:

бот должен постоянно работать как процесс;

чуть сложнее масштабировать на несколько экземпляров.

В python-telegram-bot это знакомый вариант:

Документация:

python-telegram-bot — Running your bot

Telegram Bot API — getUpdates

Webhook

Webhook означает, что Telegram сам отправляет обновления на ваш публичный URL.

Когда webhook хорош:

вы разворачиваете бота как сервис;

вы готовы настроить домен и HTTPS;

вы хотите более «серверный» стиль (Telegram сам присылает события).

Минусы webhook:

нужен публичный адрес и HTTPS;

требуется настройка веб-сервера или встроенного веб-сервера библиотеки.

Документация:

Telegram Bot API — setWebhook

Быстрый выбор для новичка

Если вы хотите быстро запустить бота на VPS и не трогать домены и сертификаты, выбирайте polling.

Если вы уже уверенно чувствуете себя с сервером и хотите правильную «боевую» схему, выбирайте webhook.

В этом курсе базовый продакшн-путь проще начать с polling на VPS, а webhook рассматривать как следующий уровень.

Где разместить бота: варианты деплоя

VPS (виртуальный сервер)

Это самый универсальный вариант: вы получаете Linux-сервер и контролируете всё.

Плюсы:

стабильно и предсказуемо;

удобно для SQLite и файлов;

можно выбрать polling или webhook.

Минусы:

нужно немного разобраться в Linux и настройке сервиса.

PaaS (платформы «задеплой из Git»)

Примеры:

Render

Railway

Fly.io

Плюсы:

минимум ручной настройки;

часто есть автодеплой из репозитория.

Минусы:

ограничения бесплатных тарифов;

для webhook всё равно нужен HTTPS маршрут (обычно платформа его даёт);

иногда сложнее с постоянным диском (для SQLite) в дешёвых планах.

Мини-чеклист продакшна

Код запускается из чистого окружения: venv, requirements.txt.

Секреты в переменных окружения: токен и ключи не в коде.

Есть автозапуск процесса: например, systemd.

Логи пишутся: и вы умеете их смотреть.

Есть обработчик ошибок: чтобы бот не «умирал молча».

Есть план обновлений: как вы выкатываете новую версию.

Продакшн на VPS с polling и systemd

Ниже типовой и очень практичный сценарий: Ubuntu-сервер, бот запускается через systemd и работает в режиме polling.

Подготовка сервера

Установите базовые пакеты:

Проверьте версии:

Разворачиваем проект

Клонируйте репозиторий (или загрузите код другим способом):

Создайте окружение и поставьте зависимости:

Создайте .env на сервере (в корне проекта, как вы делали локально):

Содержимое:

Важно, чтобы .env не попадал в Git. В продакшне вы обычно вообще не храните .env в репозитории.

Сервис systemd

systemd умеет:

запускать бота при старте сервера;

перезапускать при падении;

хранить логи.

Создайте файл сервиса:

Пример содержимого:

Что здесь важно:

WorkingDirectory указывает на корень проекта.

EnvironmentFile подключает .env как переменные окружения.

ExecStart запускает Python из вашего виртуального окружения.

Применяем и запускаем:

Проверка статуса:

Логи:

Как обновлять код без сюрпризов

Минимальная безопасная последовательность:

git pull

при изменении зависимостей: pip install -r requirements.txt

sudo systemctl restart mybot

посмотреть логи journalctl -u mybot -f

Webhook в продакшне: что нужно понимать

Webhook потребует публичного HTTPS адреса.

Практическая схема чаще всего такая:

домен (например, bot.example.com)

Nginx как reverse proxy

сертификат от Let’s Encrypt

бот принимает запросы на локальном порту

!Типовая продакшн-схема webhook на сервере

Запуск webhook в python-telegram-bot

У python-telegram-bot есть режим webhook. Пример идеи запуска:

Смысл параметров:

listen и port: где ваш бот слушает входящие HTTP-запросы.

url_path: путь, который будет принимать апдейты.

webhook_url: публичный адрес, который увидит Telegram.

Документация библиотеки может меняться по версиям, поэтому сверяйтесь с актуальной:

python-telegram-bot — Documentation

Что важно при webhook

HTTPS обязателен для большинства реальных сценариев.

Если вы переходите с polling на webhook, нужно удалить старую настройку webhook или polling-конфликт.

В Telegram webhook настраивается через setWebhook, а снимается через deleteWebhook.

Документация:

Telegram Bot API — deleteWebhook

Безопасность: что обязательно сделать

Защита токена и ключей

Правила, которые должны стать привычкой:

Никогда не храните токен в коде.

Никогда не коммитьте токен.

Храните секреты в переменных окружения: .env на сервере или секреты платформы (Render/Railway/Fly).

Если токен утёк, перевыпустите его в BotFather.

Минимальные права и осторожность с входными данными

Считайте любой ввод пользователя потенциально «плохим».

Проверяйте типы сообщений: текст, фото, файл, стикер.

Ставьте лимиты: максимальная длина текста, размер файла.

Зависимости и обновления

Фиксируйте зависимости в requirements.txt.

Обновляйте зависимости осознанно, а не случайно.

Следите за обновлениями Python и библиотек, особенно если бот публичный.

Логи без секретов

Не логируйте токен.

Осторожно с логированием объектов целиком: там могут оказаться персональные данные.

Мониторинг и отладка в продакшне

Логирование

У вас уже было базовое логирование. В продакшне важно:

логи должны сохраняться (например, journalctl через systemd);

по логам должно быть видно, что бот жив и что он делает.

Хорошая практика:

логировать старт бота;

логировать ключевые действия (команды, ошибки API, запись в базу);

логировать исключения через глобальный error handler.

Глобальный обработчик ошибок

Вы уже видели идею обработчика ошибок. В продакшне это критично: вы хотите видеть stack trace в логах и отдавать пользователю понятный ответ.

Документация:

python-telegram-bot — Application.add_error_handler

Внешний мониторинг доступности

Даже если бот пишет логи, полезно иметь внешний «пинг», который проверяет, что сервис жив.

Популярный вариант для простого мониторинга:

UptimeRobot

Polling-бот сложнее проверять HTTP-пингом, но можно:

поднять простую HTTP-точку здоровья (если у вас есть веб-сервер);

или мониторить процесс через systemd и оповещения на сервере.

Мониторинг ошибок (ошибки как события)

Для реальных проектов удобно отправлять исключения в сервис ошибок, чтобы получать уведомления.

Один из стандартов:

Sentry

Смысл простой:

исключение случилось;

вы получили событие с деталями;

вы можете быстро исправить.

Практические нюансы для бота с данными (SQLite, файлы)

Если вы используете SQLite из прошлой статьи, помните:

файл базы (data/bot.db) должен быть на диске, который не исчезает при перезапуске контейнера или сервиса;

делайте резервные копии, если данные ценны;

при деплое на PaaS уточните, есть ли постоянный диск.

Для файлового хранилища JSON правила те же: файл должен быть на постоянном диске и защищён от случайной перезаписи.

Итог

Вы теперь понимаете, как довести учебного Telegram-бота до состояния «работает как сервис»:

выбрать polling или webhook;

развернуть бота на VPS или платформе;

настроить автозапуск и логи;

защитить токены и секреты;

включить мониторинг и обработку ошибок.

С этого момента ваш бот становится не просто кодом, а небольшим, но настоящим продуктом, который можно поддерживать и развивать.