С чего начать разработку бота на Python: пошаговый старт

Чтобы создать своего первого бота в Telegram на языке Python, вам понадобится библиотека python-telegram-bot (версии 20+), токен от @BotFather и базовое понимание асинхронного программирования. Весь процесс от регистрации до запуска работающего скрипта занимает около 15 минут. Ниже приведена подробная инструкция по установке, настройке окружения и написанию кода для обработки команд, текстовых сообщений и интерактивных кнопок.

Получение токена и регистрация бота

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

1. Найдите в поиске Telegram аккаунт @BotFather.
2. Отправьте команду /newbot.
3. Введите имя бота (отображаемое имя, например: «Мой Помощник»).
4. Придумайте уникальный юзернейм (ссылка), который обязательно должен заканчиваться на _bot (например: my_super_helper_bot).
5. Если имя свободно, BotFather пришлет сообщение с токеном вида 123456:ABC-DEF....

Сразу после получения токена найдите своего нового бота по юзернейму и нажмите Start (/start). Если бот ответил приветствием — регистрация прошла успешно.

Установка и настройка окружения

Библиотека python-telegram-bot требует Python версии 3.8 или выше. Для установки используйте пакетный менеджер pip:

pip install python-telegram-bot

На текущий момент (2026 год) актуальной является ветка версий 21.x, которая полностью построена на асинхронности (asyncio). Это критически важно: все функции-обработчики должны быть объявлены как async, а вызовы методов бота — с ключевым словом await.

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

python -c "import telegram; print(telegram.__version__)"

Для работы импортируйте основные классы:

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

Пишем код первого бота (Echo-бот)

Создайте файл bot.py и вставьте следующий код. Он реализует простейшую логику: ответ на команду /start и повторение любого отправленного текста (эхо).

import logging
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

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

# Обработчик команды /start
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Привет! Я ваш первый бот. Напишите мне что-нибудь.")

# Обработчик текстовых сообщений (эхо)
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    # Игнорируем команды, чтобы не дублировать ответ
    if update.message.text and not update.message.text.startswith('/'):
        await update.message.reply_text(f"Вы написали: {update.message.text}")

# Обработчик ошибок
async def error_handler(update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
    logging.error(f"Update {update} caused error {context.error}")

def main() -> None:
    # Замените 'ВАШ_ТОКЕН' на строку, полученную от BotFather
    application = Application.builder().token("ВАШ_ТОКЕН").build()

    # Регистрируем обработчики
    application.add_handler(CommandHandler("start", start))
    # Фильтр: только текст И не команда
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    
    # Глобальный обработчик ошибок
    application.add_error_handler(error_handler)

    # Запуск поллинга (опроса сервера)
    logging.info("Бот запущен...")
    application.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == "__main__":
    main()

Запустите скрипт командой python bot.py. Теперь любой текст, отправленный боту в личные сообщения, будет возвращаться вам обратно.

Добавление интерактивности: кнопки и меню

Статические ответы быстро надоедают. Библиотека позволяет создавать инлайн-клавиатуры (кнопки под сообщением). Рассмотрим пример команды /menu, которая предлагает пользователю выбор.

Добавьте новые импорты и функции в ваш скрипт:

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, CallbackQuery

async def menu_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    keyboard = [
        [InlineKeyboardButton("📊 Статистика", callback_data='stats')],
        [InlineKeyboardButton("ℹ️ О проекте", callback_data='about'),
         InlineKeyboardButton("🔗 Сайт", url="https://example.com")]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text("Выберите действие:", reply_markup=reply_markup)

async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    query: CallbackQuery = update.callback_query
    await query.answer() # Обязательно подтверждаем нажатие, чтобы убрать часики загрузки
    
    if query.data == 'stats':
        await query.edit_message_text("Здесь могла бы быть ваша статистика использования.")
    elif query.data == 'about':
        await query.edit_message_text("Бот создан на python-telegram-bot v21+. Версия стабильна.")

Не забудьте зарегистрировать новые хендлеры в функции main():

application.add_handler(CommandHandler("menu", menu_command))
application.add_handler(CallbackQueryHandler(button_callback))

Теперь команда /menu выведет сообщение с кнопками. Нажатие на них изменит текст сообщения или откроет ссылку.

Выбор режима работы: Polling или Webhook

В примере выше использовался метод run_polling(). Это самый простой способ запуска, идеальный для разработки и тестов на локальном компьютере. Бот сам опрашивает серверы Telegram каждые несколько секунд на наличие новых сообщений.

Однако для серьезных проектов с высокой нагрузкой рекомендуется использовать Webhooks. В этом режиме сервер Telegram сам отправляет обновления на ваш адрес (URL), когда они появляются.

Частые ошибки новичков

При разработке ботов часто возникают следующие проблемы:

• Ошибка 401 Unauthorized: Токен указан неверно, содержит лишние пробелы или был отозван (сгенерируйте новый через /revoke у BotFather).
• Бот не отвечает в группах: По умолчанию боты не видят сообщения в группах, если их не упомянуть. Зайдите в настройки приватности (@BotFather → /setprivacy) и отключите режим приватности (Disable), либо добавьте бота в администраторы группы.
• SyntaxError в асинхронном коде: Забыли поставить await перед вызовом метода (например, await context.bot.send_message(...)) или объявить функцию как async def.
• Дублирование ответов: Если бот реагирует на свои же сообщения или команды внутри текстового фильтра. Всегда используйте фильтр ~filters.COMMAND для обработчиков обычного текста.

FAQ

Нужно ли платить за использование API Telegram? Нет, создание и использование ботов через BotFather полностью бесплатно. Лимиты существуют только на количество сообщений в секунду (около 30 мес.), что более чем достаточно для большинства задач.

Можно ли использовать базу данных с этим ботом? Да, библиотека не ограничивает вас в выборе БД. Вы можете подключать SQLite, PostgreSQL, MongoDB или Redis прямо внутри функций-обработчиков для сохранения состояния пользователей, истории переписки или настроек.

Как остановить бота? Если он запущен в терминале, нажмите Ctrl+C. Библиотека корректно завершит соединение. Для остановки на сервере используйте системные команды (например, systemctl stop mybot или убейте процесс через kill).

Где найти документацию? Официальная документация содержит исчерпывающие примеры кода для всех версий библиотеки. Она регулярно обновляется и включает разделы по работе с файлами, оплатой и сложными сценариями диалогов.