Как создать Telegram-бот на Python: руководство для программистов

Для кого эта статья:

• Программисты и разработчики, заинтересованные в создании Telegram-ботов
• Новички в программировании, желающие автоматизировать рутинные процессы

• Люди, занимающиеся разработкой и оптимизацией проектов на Python

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

Создание Telegram бота с нуля: подготовка среды разработки

Прежде чем погрузиться в код, необходимо правильно настроить среду разработки. Это фундамент, на котором будет строиться весь проект, поэтому важно уделить этому шагу достаточное внимание.

Первым делом убедимся, что у нас установлен Python версии 3.7 или выше. Это минимальное требование для большинства современных библиотек для работы с Telegram API. Проверить версию Python можно командой:

python --version

Для работы с ботом нам понадобится виртуальное окружение — это изолированное пространство с собственными зависимостями, которое предотвратит конфликты библиотек. Создадим его:

python -m venv tg_bot_env
source tg_bot_env/bin/activate # Для Linux/MacOS
tg_bot_env\Scripts\activate # Для Windows

Теперь установим необходимые библиотеки. Наиболее популярны три варианта:

Для новичков я рекомендую начать с telebot из-за низкого порога входа, но в этом руководстве мы рассмотрим примеры с использованием python-telegram-bot, так как эта библиотека обеспечивает лучший баланс между возможностями и сложностью.

Установим её:

pip install python-telegram-bot

Также понадобится редактор кода. Я рекомендую Visual Studio Code с установленными расширениями для Python:

• Python (официальное расширение от Microsoft)
• Pylance для улучшенного автозаполнения
• Python Docstring Generator для автоматического создания документации
• Git Integration для контроля версий

После этого создайте структуру проекта:

mkdir telegram_bot
cd telegram_bot
touch main.py
touch config.py
mkdir handlers
touch handlers/__init__.py
touch handlers/commands.py
touch README.md

Антон Соколов, Lead Python-разработчик

Помню, как в 2019 году команда из 5 человек потратила две недели на создание первого Telegram-бота для автоматизации HR-процессов. Мы сталкивались с множеством ошибок из-за неправильной настройки окружения: конфликты зависимостей, разные версии библиотек у членов команды, проблемы с токенами... После очередного срыва дедлайна я разработал стандартизированный процесс настройки, включающий Docker-контейнеризацию и автоматическую установку зависимостей. Это сократило время запуска новых проектов с дней до часов. Теперь первое, что я делаю при старте проекта — настраиваю CI/CD пайплайн и Docker-контейнер с окружением. Это инвестиция, которая окупается уже на второй день разработки.

Регистрация и настройка бота через BotFather

BotFather — это официальный бот Telegram, который помогает создавать и управлять ботами. Через него мы получим токен доступа — уникальный идентификатор, необходимый для взаимодействия с API Telegram. 🤖

Процесс регистрации нового бота:

1. Откройте Telegram и найдите BotFather (@BotFather)
2. Отправьте команду /newbot
3. Укажите имя вашего бота (может содержать любые символы)
4. Введите уникальное имя пользователя для бота (должно заканчиваться на "bot")

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

Важно: сразу же сохраните токен в файле конфигурации, отделив его от основного кода. Создайте файл config.py:

# config.py
TOKEN = 'your_token_here'

# Другие настройки
BOT_USERNAME = '@your_bot_username'
ADMIN_IDS = [123456789] # ID администраторов бота

BotFather предоставляет множество дополнительных команд для настройки вашего бота:

Особое внимание стоит уделить команде /setcommands. Она позволяет пользователям видеть список доступных команд при вводе "/". Формат ввода должен быть таким:

start – Запустить бота
help – Показать справку
settings – Настройки бота
stats – Показать статистику

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

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

Основы разработки бота на Python: выбор библиотеки

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

1. python-telegram-bot

Это полноценная обертка над Telegram Bot API с обширной документацией. Библиотека построена на принципах объектно-ориентированного программирования и предоставляет доступ ко всем возможностям API.

Преимущества:

• Полная реализация Bot API
• Поддержка как синхронного, так и асинхронного режимов работы
• Встроенные механизмы обработки разговорных контекстов (ConversationHandler)
• Обширная документация с примерами

Недостатки:

• Более высокий порог входа для новичков
• Требует понимания концепций обработчиков и диспетчеров

2. aiogram

Современная асинхронная библиотека, использующая asyncio и aiohttp. Она изначально разрабатывалась с учетом асинхронности.

Преимущества:

• Высокая производительность благодаря асинхронности
• Встроенная поддержка FSM (Finite State Machine) для управления диалогами
• Удобная система фильтров для обработки сообщений
• Интеграция с базами данных через aiogram-dialog

Недостатки:

• Требует понимания асинхронного программирования
• Менее подробная документация на английском (хотя русская документация отличная)

3. pyTelegramBotAPI (telebot)

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

Преимущества:

• Низкий порог входа
• Интуитивно понятный синтаксис
• Хорошо подходит для простых ботов
• Множество готовых примеров в сети

Недостатки:

• Ограниченная функциональность для сложных сценариев
• Нет встроенной асинхронности (хотя есть aiohttp-версия)
• Менее продвинутые инструменты для обработки состояний

Максим Петров, Senior Backend-разработчик

В 2021 году я работал над проектом автоматизации техподдержки. Клиент настаивал на скорейшей разработке MVP, поэтому мы выбрали pyTelegramBotAPI за его простоту. За три дня создали базовую версию, которая обрабатывала заявки пользователей. Однако через месяц, когда количество пользователей превысило 1000, мы столкнулись с серьезными проблемами производительности. Пришлось полностью переписывать код на aiogram с асинхронной обработкой запросов. Это потребовало дополнительных двух недель работы. Урок, который я извлек: всегда оценивайте потенциальный масштаб проекта перед выбором библиотеки. Для небольших ботов telebot идеален, но для потенциально масштабных проектов лучше сразу использовать aiogram или python-telegram-bot с асинхронностью, даже если начальная разработка займет больше времени.

Для дальнейшей работы мы будем использовать python-telegram-bot, так как эта библиотека обеспечивает хороший баланс между функциональностью и сложностью, а также имеет отличную документацию на английском языке.

Написание первого работающего Telegram бота с кодом

Теперь создадим базовый функциональный бот, способный отвечать на простые команды. Мы используем библиотеку python-telegram-bot версии 13.x, которая проще для понимания основных концепций.

Сначала структурируем код в файле main.py:

# main.py
import logging
from telegram import Update
from telegram.ext import Updater, CommandHandler, MessageHandler, Filters, CallbackContext
from config import TOKEN

# Настройка логирования
logging.basicConfig(
format='%(asctime)s – %(name)s – %(levelname)s – %(message)s', 
level=logging.INFO
)
logger = logging.getLogger(__name__)

# Обработчик команды /start
def start(update: Update, context: CallbackContext) -> None:
user = update.effective_user
update.message.reply_text(
f'Привет, {user.first_name}! Я твой первый Telegram бот. 👋\n'
f'Используй /help для получения списка команд.'
)

# Обработчик команды /help
def help_command(update: Update, context: CallbackContext) -> None:
update.message.reply_text(
'Доступные команды:\n'
'/start – Начать общение с ботом\n'
'/help – Показать эту справку\n'
'/echo [текст] – Бот повторит ваше сообщение'
)

# Обработчик команды /echo
def echo(update: Update, context: CallbackContext) -> None:
if context.args:
# Объединяем все аргументы в одну строку
text = ' '.join(context.args)
update.message.reply_text(f'Вы сказали: {text}')
else:
update.message.reply_text('Пожалуйста, добавьте текст после команды /echo')

# Обработчик всех текстовых сообщений
def handle_message(update: Update, context: CallbackContext) -> None:
text = update.message.text
update.message.reply_text(f'Вы отправили: {text}')

def main() -> None:
# Создаем объект Updater и передаем ему токен бота
updater = Updater(TOKEN)

# Получаем диспетчера для регистрации обработчиков
dispatcher = updater.dispatcher

# Регистрируем обработчики команд
dispatcher.add_handler(CommandHandler("start", start))
dispatcher.add_handler(CommandHandler("help", help_command))
dispatcher.add_handler(CommandHandler("echo", echo))

# Регистрируем обработчик для всех текстовых сообщений
dispatcher.add_handler(MessageHandler(Filters.text & ~Filters.command, handle_message))

# Запускаем бота
updater.start_polling()
logger.info("Бот запущен!")

# Держим бота запущенным до принудительного завершения
updater.idle()

if __name__ == '__main__':
main()

Запустите бота командой:

python main.py

После запуска найдите своего бота в Telegram и отправьте ему команду /start.

Разберём ключевые элементы кода:

• Updater — главный класс, который получает обновления от Telegram API и передает их обработчикам
• Dispatcher — распределяет обновления по соответствующим обработчикам
• CommandHandler — обрабатывает команды вида /command
• MessageHandler — обрабатывает различные типы сообщений
• Filters — фильтры для выбора сообщений, которые должны обрабатываться

Каждый обработчик представляет собой функцию, которая принимает два аргумента:

• update — содержит информацию о входящем обновлении
• context — предоставляет доступ к различным контекстным данным и методам

Для долговременной работы бота необходимо настроить его автоматический запуск на сервере. Для этого можно использовать systemd (Linux) или другие системы управления процессами.

Пример простого systemd-сервиса для бота:

[Unit]
Description=Telegram Bot Service
After=network.target

[Service]
User=username
WorkingDirectory=/path/to/telegram_bot
ExecStart=/path/to/telegram_bot/tg_bot_env/bin/python main.py
Restart=always

[Install]
WantedBy=multi-user.target

Сохраните этот файл как /etc/systemd/system/telegrambot.service, затем включите и запустите сервис:

sudo systemctl enable telegrambot
sudo systemctl start telegrambot

Продвинутые функции: обработка команд и медиафайлов

После создания базового бота перейдем к более продвинутым функциям: обработке различных типов медиафайлов и сложных команд с параметрами. 📊

Расширим наш бот, добавив следующие возможности:

1. Получение и обработка изображений
2. Отправка различных типов сообщений (текст, фото, документы)
3. Работа с инлайн-кнопками
4. Обработка команд с параметрами

Модифицируем наш код:

# main.py (расширенная версия)
import logging
import os
from telegram import Update, InlineKeyboardMarkup, InlineKeyboardButton
from telegram.ext import Updater, CommandHandler, MessageHandler, Filters, CallbackContext, CallbackQueryHandler
from config import TOKEN

# Настройка логирования (без изменений)
logging.basicConfig(
format='%(asctime)s – %(name)s – %(levelname)s – %(message)s', 
level=logging.INFO
)
logger = logging.getLogger(__name__)

# Обработчик команды /start (без изменений)
def start(update: Update, context: CallbackContext) -> None:
user = update.effective_user
update.message.reply_text(
f'Привет, {user.first_name}! Я твой первый Telegram бот. 👋\n'
f'Используй /help для получения списка команд.'
)

# Обработчик команды /help (расширенный)
def help_command(update: Update, context: CallbackContext) -> None:
update.message.reply_text(
'Доступные команды:\n'
'/start – Начать общение с ботом\n'
'/help – Показать эту справку\n'
'/echo [текст] – Бот повторит ваше сообщение\n'
'/button – Показать интерактивные кнопки\n'
'/weather [город] – Показать погоду в указанном городе\n\n'
'Бот также реагирует на отправленные фото и документы!'
)

# Обработчик фотографий
def handle_photo(update: Update, context: CallbackContext) -> None:
# Получаем информацию о фото
photo_file = update.message.photo[-1].get_file()
file_id = update.message.photo[-1].file_id

# Сообщаем пользователю
update.message.reply_text(
f'Получено изображение! File ID: {file_id[:10]}...\n'
f'Размер: {photo_file.file_size} байт'
)

# Можно сохранить изображение локально
# photo_file.download('user_photo.jpg')

# Отправляем то же изображение обратно
update.message.reply_photo(
photo=file_id,
caption="Я могу также отправлять изображения!"
)

# Обработчик документов
def handle_document(update: Update, context: CallbackContext) -> None:
doc_file = update.message.document.get_file()
file_name = update.message.document.file_name

update.message.reply_text(
f'Получен документ: {file_name}\n'
f'Размер: {doc_file.file_size} байт'
)

# Обработчик команды /button
def button(update: Update, context: CallbackContext) -> None:
keyboard = [
[
InlineKeyboardButton("Вариант 1", callback_data='option1'),
InlineKeyboardButton("Вариант 2", callback_data='option2')
],
[InlineKeyboardButton("Подробнее", url='https://core.telegram.org/bots/api')]
]
reply_markup = InlineKeyboardMarkup(keyboard)

update.message.reply_text('Выберите опцию:', reply_markup=reply_markup)

# Обработчик нажатий на кнопки
def button_callback(update: Update, context: CallbackContext) -> None:
query = update.callback_query
query.answer() # Обязательно нужно ответить на callback

if query.data == 'option1':
query.edit_message_text(text="Вы выбрали первый вариант!")
elif query.data == 'option2':
query.edit_message_text(text="Вы выбрали второй вариант!")

# Команда с параметрами – простая имитация прогноза погоды
def weather(update: Update, context: CallbackContext) -> None:
if not context.args:
update.message.reply_text('Пожалуйста, укажите город: /weather Москва')
return

city = ' '.join(context.args)
# В реальном боте здесь был бы API-запрос к сервису погоды
update.message.reply_text(
f'Прогноз погоды для города {city}:\n'
f'🌡️ Температура: 25°C\n'
f'💧 Влажность: 60%\n'
f'💨 Ветер: 5 м/с\n'
f'☁️ Облачность: Переменная'
)

# Главная функция
def main() -> None:
updater = Updater(TOKEN)
dispatcher = updater.dispatcher

# Регистрируем обработчики
dispatcher.add_handler(CommandHandler("start", start))
dispatcher.add_handler(CommandHandler("help", help_command))
dispatcher.add_handler(CommandHandler("echo", echo)) # Из предыдущей версии
dispatcher.add_handler(CommandHandler("button", button))
dispatcher.add_handler(CommandHandler("weather", weather))

# Обработчики медиафайлов
dispatcher.add_handler(MessageHandler(Filters.photo, handle_photo))
dispatcher.add_handler(MessageHandler(Filters.document, handle_document))

# Обработчик текстовых сообщений (должен быть в конце)
dispatcher.add_handler(MessageHandler(Filters.text & ~Filters.command, handle_message))

# Обработчик нажатий на кнопки
dispatcher.add_handler(CallbackQueryHandler(button_callback))

# Запуск бота
updater.start_polling()
logger.info("Бот запущен с расширенными возможностями!")
updater.idle()

if __name__ == '__main__':
main()

Рассмотрим более подробно некоторые продвинутые функции:

1. Обработка фото: При отправке фотографии бот получает объект с информацией о файле, включая file_id, который можно использовать для повторной отправки.
2. Инлайн-кнопки: Позволяют создавать интерактивные меню и собирать обратную связь от пользователей.
3. Параметры команд: Возможность обрабатывать команды с аргументами (например, /weather Москва).

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

1. InlineKeyboardMarkup: Кнопки под сообщением бота
2. ReplyKeyboardMarkup: Кнопки, заменяющие клавиатуру пользователя

Пример использования ReplyKeyboardMarkup:

from telegram import ReplyKeyboardMarkup, KeyboardButton

def show_keyboard(update: Update, context: CallbackContext) -> None:
keyboard = [
[KeyboardButton('Погода'), KeyboardButton('Новости')],
[KeyboardButton('Поделиться контактом', request_contact=True)],
[KeyboardButton('Отправить местоположение', request_location=True)]
]
reply_markup = ReplyKeyboardMarkup(keyboard, resize_keyboard=True)

update.message.reply_text(
'Выберите опцию:',
reply_markup=reply_markup
)

Для более сложных ботов рекомендуется использовать состояния и конечные автоматы. В библиотеке python-telegram-bot это реализуется через ConversationHandler:

from telegram.ext import ConversationHandler

# Определяем состояния
CHOOSING, TYPING_REPLY = range(2)

def start_conversation(update: Update, context: CallbackContext) -> int:
update.message.reply_text('Начинаем опрос. Как вас зовут?')
return CHOOSING

def received_name(update: Update, context: CallbackContext) -> int:
context.user_data['name'] = update.message.text
update.message.reply_text(f'Приятно познакомиться, {context.user_data["name"]}! Сколько вам лет?')
return TYPING_REPLY

def received_age(update: Update, context: CallbackContext) -> int:
context.user_data['age'] = update.message.text
update.message.reply_text(
f'Отлично! Итак, вас зовут {context.user_data["name"]} и вам {context.user_data["age"]} лет.'
)
return ConversationHandler.END

conv_handler = ConversationHandler(
entry_points=[CommandHandler('survey', start_conversation)],
states={
CHOOSING: [MessageHandler(Filters.text & ~Filters.command, received_name)],
TYPING_REPLY: [MessageHandler(Filters.text & ~Filters.command, received_age)],
},
fallbacks=[CommandHandler('cancel', cancel)]
)

Такой подход позволяет создавать сложные диалоговые сценарии с переходами между состояниями.

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