python-telegram-bot - это python telegram bot библиотека для работы с Bot API Telegram: обёртка на Python, через которую бот получает апдейты, отправляет сообщения и собирает диалоговые сценарии в несколько шагов. Библиотека живёт на PyPI больше десяти лет и остаётся одним из двух главных вариантов для бота на Python, вторым обычно называют aiogram. Беру её, когда нужен бот с уведомлениями о заказах, интеграцией с CRM или внутренней утилитой для команды, а не готовый сценарий в n8n и не конструктор без кода. В статье разбираю архитектуру библиотеки, собираю рабочего бота с нуля и сравниваю с aiogram, чтобы было понятно, когда какая подойдёт.
Что такое python-telegram-bot и для каких задач её беру
Библиотека оборачивает HTTP-запросы к Bot API в питоновские объекты и методы: вместо ручной сборки JSON и обработки ответов есть update.message.reply_text(), готовые классы для клавиатур, файлов и медиа. Под капотом asyncio, но по умолчанию Application обрабатывает апдейты последовательно: пока один обработчик ждёт внешний API, следующие апдейты стоят в очереди. Чтобы обрабатывать их параллельно, включают ApplicationBuilder().concurrent_updates(True) или передают обработчикам block=False.
На практике такая python telegram bot библиотека закрывает три типа задач. Первая - уведомления: интернет-магазин на WooCommerce или сайт на Tilda отправляет вебхук при новом заказе, бот получает его и пишет менеджеру в чат, что пришла оплата через T‑Bank и заказ пора собирать. Вторая - сбор заявок и мини-CRM внутри Telegram, когда клиенту не нужна отдельная админка, а нужен структурированный диалог с сохранением данных в базу. Третья - служебные боты: результаты парсинга, статусы деплоя, алерты от мониторинга. Для сценариев без кода в похожих задачах я беру n8n, но там, где логика ветвится сильнее, чем позволяет визуальный редактор, или нужна специфичная Python-библиотека для обработки данных, пишу бота на python-telegram-bot напрямую.
Архитектура библиотеки: Application, апдейты и обработчики
Центральный объект - Application, который собирается через ApplicationBuilder. Он хранит очередь входящих апдейтов, список обработчиков и цикл polling или webhook. Каждый обработчик (handler) подписывается на тип события: команда, текстовое сообщение, нажатие на inline-кнопку, файл. Библиотека проверяет апдейт по очереди против зарегистрированных обработчиков и вызывает первый подходящий в пределах группы: если разнести обработчики по разным группам через параметр group в add_handler, по одному апдейту сработает несколько.
Обработчики - это обычные асинхронные функции с сигнатурой (update: Update, context: ContextTypes.DEFAULT_TYPE). Через update доступны текст сообщения, отправитель, чат. Через context - данные пользователя (user_data), данные чата (chat_data) и общие для всего бота данные (bot_data). По умолчанию все три словаря хранятся в памяти процесса и пропадают при перезапуске, если не подключена persistence, например PicklePersistence. Отдельно есть JobQueue - планировщик на базе APScheduler для отложенных и повторяющихся задач, например напоминания «оплатите заказ» через сутки после создания заявки, без внешнего cron. Он ставится как опциональная зависимость командой pip install "python-telegram-bot[job-queue]", без неё context.job_queue равен None. Задачи хранятся в памяти процесса и при перезапуске теряются.
Фильтры из модуля filters уточняют, на что реагирует обработчик: только текст, только команды, сообщения от конкретного пользователя, файлы определённого типа. Комбинируются через & и ~, как в примере ниже с исключением команд из обработчика обычного текста.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Первый рабочий бот на python-telegram-bot за 5 шагов
- Создать бота через @BotFather в Telegram командой
/newbotи получить токен - без него библиотека не сможет авторизоваться в Bot API. - Установить версию Python, которую поддерживает актуальный релиз библиотеки (указана на PyPI), и создать виртуальное окружение, чтобы зависимости бота не смешивались с другими проектами.
- Поставить саму библиотеку.
- Написать код с обработчиками команд и текстовых сообщений.
- Запустить файл и проверить бота в Telegram.
Установка выполняется одной командой:
pip install python-telegram-bot
Минимальный рабочий бот, который отвечает на команду /start и повторяет любое текстовое сообщение:
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, filters, ContextTypes
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text("Привет! Я бот на python-telegram-bot.")
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text(update.message.text)
if __name__ == "__main__":
app = ApplicationBuilder().token("ВАШ_ТОКЕН").build()
app.add_handler(CommandHandler("start", start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
app.run_polling()
Запускается командой python bot.py. Метод run_polling() держит процесс живым и сам опрашивает Telegram на новые апдейты - этого достаточно и для локальной разработки, и для большинства ботов на сервере.
Команды, кнопки и ConversationHandler для сценариев
Когда диалог состоит из одного вопроса-ответа, хватает обычных обработчиков. Но для формы из нескольких шагов - как «имя, телефон, комментарий» при приёме заявки - есть ConversationHandler: он держит состояние диалога и переключает, какой обработчик сработает на следующем сообщении пользователя.
from telegram import ReplyKeyboardRemove
from telegram.ext import ApplicationBuilder, ConversationHandler, MessageHandler, CommandHandler, filters, ContextTypes
NAME, PHONE = range(2)
async def start_order(update, context):
await update.message.reply_text("Как вас зовут?")
return NAME
async def get_name(update, context):
context.user_data["name"] = update.message.text
await update.message.reply_text("Укажите телефон для связи")
return PHONE
async def get_phone(update, context):
context.user_data["phone"] = update.message.text
await update.message.reply_text("Заявка принята, скоро свяжемся", reply_markup=ReplyKeyboardRemove())
return ConversationHandler.END
async def cancel(update, context):
await update.message.reply_text("Отменено")
return ConversationHandler.END
conv_handler = ConversationHandler(
entry_points=[CommandHandler("order", start_order)],
states={
NAME: [MessageHandler(filters.TEXT & ~filters.COMMAND, get_name)],
PHONE: [MessageHandler(filters.TEXT & ~filters.COMMAND, get_phone)],
},
fallbacks=[CommandHandler("cancel", cancel)],
)
if __name__ == "__main__":
app = ApplicationBuilder().token("ВАШ_ТОКЕН").build()
app.add_handler(conv_handler)
app.run_polling()
Если сценарий добавляется в бота из первого листинга, conv_handler регистрирую раньше обработчика echo в той же группе: иначе echo из группы 0 перехватит ответ с именем, и шаги сценария не вызовутся. Если вынести conv_handler в другую группу через параметр group, сработают оба обработчика, и echo повторит имя и телефон.
Для инлайн-кнопок используется связка InlineKeyboardMarkup и CallbackQueryHandler: кнопка отправляет боту не текст, а callback-данные, и по ним определяется, какое действие выбрал пользователь. Так делаю каталоги услуг внутри бота или подтверждение заказа без набора текста.
python-telegram-bot или aiogram: что выбрать
Обе библиотеки решают одну задачу, но по-разному организуют диалоги и сообщество вокруг них разное.
| Критерий | python-telegram-bot | aiogram |
|---|---|---|
| Модель диалога | ConversationHandler со списком состояний | FSM (конечный автомат) через StatesGroup, FSMContext и хранилище состояний |
| Документация | Подробная, в основном на английском | Хорошая, много статей и примеров на русском |
| Стиль кода | Декларативная регистрация обработчиков в Application | Роутеры с декораторами, ближе к веб-фреймворкам |
| Планировщик задач | JobQueue на базе APScheduler, ставится через extra [job-queue] | Нет своего, APScheduler или похожие пакеты подключают отдельно |
На практике выбор чаще решает не техническая разница, а то, что уже знает команда. Если в проекте уже есть код на aiogram, не переписываю его на python-telegram-bot без причины. Для нового проекта беру python-telegram-bot, когда нужен предсказуемый ConversationHandler под многошаговую форму и планировщик JobQueue, который подключается через extra [job-queue].
Где и как запускать Telegram-бота на Python
Бот на python-telegram-bot должен держать постоянно работающий процесс: либо он опрашивает Telegram через polling, либо принимает вебхуки на открытый HTTPS-адрес. Обычный shared-хостинг для сайта на Tilda или WordPress для этого не подходит - там нет постоянно живого процесса, только обработка входящих HTTP-запросов на лету. Под бота нужен отдельный сервер, обычно VPS: там ставится Python, процесс бота держат через systemd или менеджер процессов, чтобы он поднимался заново после падения или перезагрузки сервера. Это отдельная строка расходов помимо хостинга сайта - сервер нужно арендовать, обновлять и оплачивать помесячно, и это стоит учитывать до старта разработки, а не после.
Polling проще в настройке и подходит для большинства ботов среднего размера: не нужен домен с SSL-сертификатом, бот сам держит long polling запрос к Telegram и получает апдейты, как только они приходят. Webhook эффективнее при высокой нагрузке, но требует HTTPS-адрес, который Telegram сможет достучаться, и библиотека умеет поднимать веб-сервер для приёма вебхуков, если установить её с extra python-telegram-bot[webhooks].
Если не хочется самостоятельно разбираться с сервером, обработчиками и ConversationHandler, обычно предлагаю клиентам разработку Telegram-бота на заказ - от постановки сценария до деплоя и передачи владения ботом клиенту.
Bot API Telegram и python-telegram-bot регулярно обновляются, поэтому перед запуском я сверяюсь с актуальной документацией и changelog библиотеки.
Частые вопросы
Чем python-telegram-bot отличается от aiogram?
Обе библиотеки асинхронные и решают одинаковый круг задач, разница в организации кода: python-telegram-bot строит диалоги через ConversationHandler и Application с JobQueue, который подключается через extra [job-queue], aiogram опирается на роутеры и FSM, ближе по стилю к веб-фреймворкам вроде FastAPI. Выбор часто определяется тем, что уже знает команда, а не принципиальным техническим превосходством одной библиотеки над другой.
Нужен ли отдельный сервер для бота на python-telegram-bot?
Да. Бот работает как постоянно запущенный Python-процесс, который либо опрашивает Telegram, либо принимает вебхуки. Обычный хостинг сайта на Tilda или WordPress для этого не годится, нужен VPS с Python и менеджером процессов вроде systemd, который перезапустит бота после сбоя.
Можно ли использовать python-telegram-bot в коммерческом проекте?
Библиотека распространяется под лицензией LGPLv3 и используется в коммерческих ботах без ограничений на сам факт использования. Условия лицензии касаются изменений самой библиотеки: изменённую библиотеку нужно распространять под LGPL. Отдельный вопрос - поддержка и доработка написанного на ней бота: это уже не про лицензию библиотеки, а про то, кто будет чинить код при обновлении зависимостей или изменении Bot API.
Что делать, если бот перестал отвечать после обновления библиотеки?
Первым делом смотрю changelog версии, до которой обновились: с переходом на асинхронную архитектуру у библиотеки заметно менялись сигнатуры методов и структура импортов, и старый код на Updater не запустится на новом Application без переписывания обработчиков. Перед обновлением в проде фиксирую версию в requirements и тестирую апдейт на копии бота, а не на боевом токене.