Как написать простой чат-бот на Python с помощью библиотеки telebot

Что такое telebot и когда её выбрать

pyTelegramBotAPI оборачивает вызовы Telegram Bot API в обычные методы Python: отправить сообщение, показать кнопки, скачать файл. По умолчанию библиотека синхронная — каждый вызов дожидается ответа сервера, прежде чем перейти к следующей строке кода, и это заметно упрощает чтение логики по сравнению с асинхронным кодом на await. Для небольших и средних ботов с обычным длинным опросом сервера такой подход работает без проблем и не требует отдельного знакомства с asyncio.

Токен для бота telebot получают тем же способом, что и для любой другой библиотеки — через служебный аккаунт BotFather внутри самого Telegram, командой /newbot. Пошаговая инструкция именно этого шага подробно разобрана в отдельном материале на сайте, а здесь сосредоточимся на самой библиотеке и её возможностях.

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

Пакет на PyPI называется pyTelegramBotAPI, а вот импортируют его под другим именем — telebot, и это частая причина путаницы у новичков, которые ищут пакет по имени модуля и не находят. После установки объект бота создают одной строкой: telebot.TeleBot с полученным от BotFather токеном в аргументе. Токен стоит держать в переменной окружения, а не прямо в коде — так же поступают с любым другим секретом проекта.

Полезная привычка на старте — сразу вызвать у объекта бота метод get_me и вывести результат на экран. Если токен верный, в ответ придут имя и технический username бота, и это подтверждает, что дальше можно спокойно писать обработчики, не тратя время на отладку опечатки в токене.

Декораторы-обработчики сообщений

Декоратор message_handler размещают прямо над функцией и указывают в скобках условие, при котором telebot должен вызвать эту функцию. Параметр commands ловит конкретные команды вроде start или help, параметр content_types различает текст, фото, документы и голосовые сообщения, а параметр regexp ловит текст по шаблону. Функция получает на вход объект message с текстом, идентификатором чата, отправителем и другими деталями входящего сообщения.

Простейший обработчик отвечает на любое текстовое сообщение через bot.reply_to или bot.send_message, где первым аргументом идёт либо сам объект message, либо идентификатор чата из message.chat.id. Разница небольшая: reply_to дополнительно оформляет ответ как цитату исходного сообщения в интерфейсе Telegram, а send_message отправляет обычное новое сообщение.

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

У telebot есть два вида кнопок с разным поведением. ReplyKeyboardMarkup заменяет обычную клавиатуру устройства собственным набором кнопок пользователя, и нажатие такой кнопки приходит боту как самое обычное текстовое сообщение. InlineKeyboardMarkup крепит кнопки прямо под текстом сообщения в чате и работает иначе — через отдельное событие нажатия, а не через текст.

Для inline-кнопок нужен свой декоратор callback_query_handler, который ловит нажатия по значению callback_data — короткой строке, зашитой в каждую кнопку при её создании. После обработки нажатия бот обязан вызвать bot.answer_callback_query, иначе кнопка в интерфейсе Telegram так и останется крутиться в состоянии ожидания у пользователя.

Состояния диалога

Простое состояние многошагового диалога хранят в обычном словаре, где ключ — идентификатор пользователя, а значение — название текущего шага, например ожидание имени или ожидание номера группы. Каждый обработчик сначала смотрит в этот словарь, чтобы понять, как истолковать пришедшее сообщение, а в конце обновляет запись под тем же ключом перед переходом к следующему шагу.

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

Обработка ошибок и вежливое поведение без сети

Запуск через bot.infinity_polling переживает короткие обрывы сети сам, делает паузу и продолжает опрос заново, тогда как обычный bot.polling при первом же сетевом сбое завершает работу и требует ручного перезапуска процесса. Параметры timeout и none_stop у infinity_polling настраивают, сколько ждать ответа сервера и не останавливаться ли при внутренних исключениях обработчиков.

Отправку сообщения полезно оборачивать в проверку на собственное исключение библиотеки telebot.apihelper.ApiException — оно прилетает, например, если пользователь заблокировал бота или чат больше не существует. Без такой проверки один неудачный адресат может остановить рассылку для всех остальных. При долгой недоступности сервера стоит увеличивать паузу между повторными попытками, а не долбить Telegram запросами каждую секунду подряд.

• два экземпляра скрипта запущены одновременно с одним токеном, и Telegram отвечает ошибкой конфликта опроса
• обработчик описан в коде после запуска polling, а не до него, поэтому декоратор так и не сработал
• необработанное исключение внутри одного обработчика останавливает весь процесс без infinity_polling
• inline-кнопка нажата, а answer_callback_query не вызван, и кнопка выглядит зависшей у пользователя