Как создать Telegram-бота на Python с нуля
Telegram-бот на Python: короткий план запуска
- Опишите одно целевое действие: ответ, заявка, запись, заказ или уведомление.
- Создайте бота через официальный @BotFather и сохраните токен вне исходного кода.
- Установите актуальную поддерживаемую версию Python и создайте отдельное виртуальное окружение.
- Выберите один фреймворк: aiogram или python-telegram-bot.
- Добавьте /start, один основной обработчик, понятную ошибку и передачу оператору.
- Запустите polling для локальной разработки, а перед production выберите polling или webhook осознанно.
- Добавьте хранение состояния, логи, мониторинг, резервное копирование и только затем ведите трафик.
Если аккаунт ещё не зарегистрирован, начните с общей инструкции по созданию Telegram-бота: там разобраны BotFather, username, команды и выбор способа разработки.
Что нужно установить до начала разработки
Подготовьте Python, редактор кода, Git и виртуальное окружение. Изоляция зависимостей важна даже для маленького проекта: она фиксирует совместимые версии библиотек и уменьшает риск, что обновление другого приложения сломает бота. Секреты храните в переменных окружения или менеджере секретов, а файл с локальными значениями исключите из репозитория.
| Компонент | Для прототипа | Для production |
|---|---|---|
| Python | Поддерживаемая версия и venv | Зафиксированная версия среды и зависимостей |
| Telegram-фреймворк | aiogram или python-telegram-bot | Один выбранный стек, тесты обновлений |
| Данные | Память процесса или файл для эксперимента | Надёжная база данных и резервные копии |
| Запуск | Polling на компьютере | Серверный процесс или HTTPS webhook |
| Наблюдаемость | Вывод ошибок в консоль | Структурные логи, метрики и уведомления |
Aiogram или python-telegram-bot: что выбрать
Обе библиотеки закрывают типовые задачи Telegram Bot API. Aiogram строится вокруг асинхронного Python, роутеров, фильтров, middleware и конечных автоматов состояний. Python-telegram-bot предлагает объект Application, обработчики и готовые способы запуска через polling или webhook. Выбор влияет меньше, чем качество структуры проекта: не смешивайте бизнес-логику, запросы к базе и Telegram-обработчики в одной функции.
Не копируйте пример для старой major-версии библиотеки. Синтаксис и жизненный цикл фреймворков меняются; сверяйте шаблон с документацией установленной версии.
Правильная структура проекта Telegram-бота
Для учебного echo-бота достаточно одного файла, но бизнес-сценарий быстро разрастается. Разделите конфигурацию, обработчики, сервисы, доступ к данным и тесты. Тогда Telegram остаётся одним из каналов, а правила заявки, расчёта или заказа можно проверять независимо.
- config — чтение переменных окружения и проверка обязательных настроек;
- handlers — команды, сообщения, callback-кнопки и маршрутизация;
- services — заявки, каталог, расчёты, CRM и внешние API;
- repositories — запросы к базе данных без Telegram-специфики;
- middlewares — авторизация, язык, лимиты и единый контекст;
- tests — сценарии, ошибки интеграций и повторная доставка событий;
- main — сборка приложения и корректный запуск или остановка.
Как собрать первый рабочий сценарий
Начните с /start и одного результата. Например, бот показывает три услуги, задаёт два уточняющих вопроса, просит контакт, повторяет введённые данные и только после подтверждения создаёт заявку. Для каждого шага определите допустимый ввод, кнопку назад, отмену, тайм-аут и сообщение при технической ошибке.
Если цель — лидогенерация, используйте отдельную схему Telegram-бота для заявок: она связывает источник рекламы, квалификацию, CRM, ответственного и статус продажи.
Состояния, база данных и повторные события
Состояние диалога нельзя надёжно держать только в памяти процесса: после перезапуска оно исчезнет. Сохраняйте минимально необходимый контекст — идентификатор пользователя, текущий шаг, выбранные значения, время изменения и технический статус. Не собирайте данные «на будущее». Для телефона, адреса и других персональных сведений определите основание обработки, срок хранения и доступ команды.
Обработчики должны выдерживать повтор. Пользователь может нажать кнопку дважды, а внешняя система — повторно доставить событие. Создание заявки, заказа или оплаты делайте идемпотентным: сохраняйте уникальный ключ операции и возвращайте уже известный результат вместо дубля.
Polling или webhook для Python-бота
| Критерий | Long polling | Webhook |
|---|---|---|
| Получение обновлений | Приложение запрашивает Telegram | Telegram отправляет HTTPS POST |
| Локальная разработка | Проще начать | Нужен публичный HTTPS endpoint или туннель |
| Размещение | Нужен постоянно работающий процесс | Нужен доступный HTTPS-маршрут |
| Безопасность | Защита токена и сервера | Дополнительно проверка secret_token |
| Ограничение | Не работает при установленном webhook | Не совмещается с getUpdates |
Telegram документирует getUpdates и webhook как взаимоисключающие способы. Для webhook задайте секретный токен и проверяйте заголовок X-Telegram-Bot-Api-Secret-Token. Возвращайте успешный ответ быстро, а тяжёлую обработку переносите в очередь, иначе Telegram может повторить доставку.
Выбор VPS, облачной платформы или serverless зависит от режима обновлений и данных. Практические критерии собраны в руководстве по хостингу Telegram-бота.
Как подключать CRM, оплату и внешние API
Внешний сервис вызывайте через отдельный клиент с тайм-аутом, ограниченным числом повторов и понятным исключением. Не сообщайте пользователю «успех», пока критичная операция не подтверждена системой-источником. Для CRM сохраняйте внешний ID и статус синхронизации. Для оплаты проверяйте результат на backend, а не по сообщению клиента.
Для генеративных ответов добавляется ещё один backend-вызов. Полная схема, защита ключей и контроль фактов разобраны в статье как подключить ChatGPT к Telegram-боту.
Безопасность токена и пользовательских данных
- Не храните токен BotFather и ключи API в коде, скриншотах и публичном Git-репозитории.
- Ограничьте доступ к production-секретам и ведите журнал их замены.
- При утечке сразу перевыпустите токен через BotFather и обновите среду.
- Проверяйте тип, длину и допустимые значения каждого пользовательского поля.
- Не записывайте в логи полные телефоны, документы, платёжные данные и тексты приватных диалогов.
- Разделите права администратора, оператора и технической поддержки.
- Ограничьте частоту запросов и обработайте массовые повторные нажатия.
Что проверить перед запуском
Пройдите сценарий с нового аккаунта и с уже заполненным профилем. Проверьте неверный текст вместо кнопки, пустое значение, длинное сообщение, повторный callback, отключение базы, тайм-аут CRM, перезапуск процесса и возврат после паузы. Отдельно проверьте русский, узбекский и смешанный ввод, если бот заявлен как двуязычный.
Готовность определяется не тем, что /start отвечает, а тем, что целевое действие завершается без дублей, данные доходят ответственному, а сбой заметен команде.
Логи, мониторинг и поддержка Python-бота
Лог должен помогать восстановить цепочку события без чтения личной переписки. Записывайте технический request ID, update_id, тип обработчика, длительность, код результата внешнего сервиса и категорию ошибки. Телефон, текст сообщения, токены и платёжные реквизиты маскируйте или не сохраняйте. Для production разделяйте информационные события и ошибки, задавайте срок хранения и ограничивайте доступ.
Мониторинг должен замечать не только падение процесса. Отслеживайте рост необработанных событий, время ответа, ошибки Telegram Bot API, базы и CRM, а также падение числа завершённых заявок. Для критичного сценария настройте уведомление ответственному и короткую инструкцию: как проверить healthcheck, логи, webhook, подключение к базе и последнюю версию.
- Добавьте correlation ID и передавайте его между обработчиком, сервисом и CRM.
- Создайте безопасную команду или endpoint для проверки состояния зависимостей.
- Проверяйте автоматический перезапуск и корректное завершение процесса.
- Храните номер версии в логах, чтобы быстро связать ошибку с deployment.
- Раз в месяц просматривайте реальные отказы и превращайте их в автоматические тесты.
Когда писать самому, а когда заказывать разработку
Самостоятельная разработка оправдана для обучения, внутреннего прототипа и простого сценария без критичных интеграций. Если бот принимает лиды из рекламы, создаёт заказы, меняет статусы в CRM, использует оплату или AI, стоимость ошибки становится выше стоимости интерфейса. Нужны аналитика требований, тестовый контур, ответственность за deployment и поддержка после запуска.
Можно передать команде готовый сценарий и получить оценку разработки Telegram-бота в Ташкенте. В ТЗ укажите роли, ветки диалога, интеграции, языки, ожидаемую нагрузку и критерии приёмки.
Итог: минимальная надёжная версия
Создайте бота через BotFather, изолируйте Python-проект, выберите актуальный фреймворк и реализуйте один измеримый сценарий. Локально используйте polling, а production-режим выбирайте с учётом инфраструктуры. Вынесите секреты, данные и интеграции в отдельные слои, предусмотрите повтор событий, наблюдаемость и передачу человеку. До рекламы проведите тест с новой учётной записью, зафиксируйте критерий успешной заявки и назначьте ответственного за технические уведомления. Такая база позволяет добавлять CRM, оплату и AI без полной переписки проекта.