Python Telegram Bot: установка и первый бот за 15 минут

Python Telegram Bot: установка и первый бот за 15 минут

Python Telegram Bot — это самая популярная библиотека для создания ботов в Telegram на языке Python. В этой статье вы узнаете, как установить python-telegram-bot через pip, получить API-токен от BotFather и запустить первого рабочего бота за 15 минут. Пошаговая инструкция с кодом, скриншотами и решениями частых ошибок.

Целевая аудитория: разработчики Python (начальный и средний уровень), которые хотят автоматизировать бизнес-процессы или создать чат-бота для Telegram.

Что такое python-telegram-bot и зачем он нужен

python-telegram-bot — это open-source библиотека (wrapper) для Telegram Bot API, написанная на Python. Она предоставляет высокоуровневый интерфейс для работы с ботами: отправка сообщений, обработка команд, работа с inline-кнопками, приём платежей и многое другое.

Почему python-telegram-bot — лучший выбор для разработки

  • ✅ Простота использования — чистый Python-код без лишних абстракций
  • ✅ Полное покрытие Telegram Bot API — поддержка всех функций: от базовых команд до веб-приложений (Mini Apps)
  • ✅ Активное комьюнити — 5342 запроса/месяц на установку через pip, тысячи примеров кода на GitHub
  • ✅ Асинхронная архитектура — поддержка async/await для высокой производительности
  • ✅ Подробная документация — официальная wiki с примерами на русском языке

Альтернативы: aiogram (для async), pyTelegramBotAPI (более лёгкая библиотека). Но для большинства задач python-telegram-bot — оптимальный выбор по балансу функциональности и простоты.

Системные требования для установки python-telegram-bot

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

1. Python 3.7 или выше

Проверьте версию Python в терминале (или командной строке Windows):

python --version
# или
python3 --version

Ожидаемый результат: Python 3.7.0 (или выше). Если версия ниже или Python не установлен, скачайте последнюю версию с python.org.

2. pip (менеджер пакетов Python)

pip обычно устанавливается вместе с Python. Проверьте:

pip --version
# или
pip3 --version

Ожидаемый результат: pip 21.0 from /usr/local/lib/python3.9/site-packages/pip (python 3.9) (версия может отличаться).

3. Базовые навыки Python

  • Понимание функций, переменных, условий
  • Опыт работы с терминалом / командной строкой
  • Знание основ ООП (классы, методы) — желательно, но не обязательно

Уровень сложности инструкции: начальный. Даже если вы новичок в Python, пошаговые команды помогут создать первого бота.

Как установить python-telegram-bot через pip: пошаговая инструкция

Установка библиотеки python-telegram-bot выполняется одной командой через pip. Следуйте шагам ниже:

Шаг 1: Откройте терминал (или командную строку)

  • Windows: нажмите Win + R, введите cmd, нажмите Enter
  • macOS: откройте Spotlight (Cmd + Space), введите Terminal
  • Linux: Ctrl + Alt + T

Шаг 2: Создайте виртуальное окружение (рекомендуется)

Виртуальное окружение изолирует зависимости проекта от системного Python. Это считается best practice.

# Создаём папку проекта
mkdir telegram_bot_project
cd telegram_bot_project

# Создаём виртуальное окружение
python -m venv venv

# Активируем окружение:
# Windows:
venv\Scripts\activate
# macOS / Linux:
source venv/bin/activate

Индикатор успеха: в начале строки терминала появится (venv).

Шаг 3: Установите python-telegram-bot через pip

Выполните команду:

pip install python-telegram-bot

Ожидаемый вывод:

Collecting python-telegram-bot
  Downloading python_telegram_bot-20.7-py3-none-any.whl (640 kB)
  ...
Installing collected packages: ...
Successfully installed python-telegram-bot-20.7 ...

Версия может отличаться — на момент написания статьи актуальна версия 20.7.

Шаг 4: Проверьте установку

Запустите Python-интерпретатор и попробуйте импортировать библиотеку:

python
>>> import telegram
>>> print(telegram.__version__)
'20.7'
>>> exit()

Если импорт прошёл без ошибок — установка завершена успешно! ✅

Альтернативная команда установки (если pip не работает)

На некоторых системах (особенно macOS/Linux с несколькими версиями Python) нужно использовать pip3:

pip3 install python-telegram-bot

Или установить для конкретной версии Python:

python3.9 -m pip install python-telegram-bot

Как получить токен API для Telegram-бота: регистрация у BotFather

Чтобы ваш Python-бот мог работать, нужен API-токен — уникальный ключ доступа к Telegram Bot API. Токен выдаёт официальный бот Telegram — @BotFather.

Шаг 1: Найдите @BotFather в Telegram

  1. Откройте Telegram (мобильное приложение или десктоп)
  2. В поиске введите @BotFather
  3. Откройте диалог с синей галочкой (это официальный бот Telegram)

Шаг 2: Создайте нового бота командой /newbot

  1. Отправьте команду: /newbot
  2. BotFather попросит указать имя бота (например: My Test Bot)
  3. Затем — username бота (должен заканчиваться на bot, например: my_test_bot)

Пример диалога:

BotFather: Alright, a new bot. How are we going to call it?
Вы: My Test Bot

BotFather: Good. Now let's choose a username for your bot.
Вы: my_test_bot

BotFather: Done! Congratulations on your new bot.
You will find it at t.me/my_test_bot.
Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

For a description of the Bot API, see this page:
https://core.telegram.org/bots/api

Шаг 3: Скопируйте токен

Токен имеет формат: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz (цифры + двоеточие + буквы/цифры).

⚠️ ВАЖНО: Не публикуйте токен в открытом доступе (GitHub, форумы) — любой, у кого есть токен, может управлять вашим ботом!

Лайфхак: Сохраните токен в файл .env и используйте библиотеку python-dotenv для безопасного хранения.

Создаём первого Telegram-бота на Python: код за 5 минут

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

Шаг 1: Создайте файл bot.py

В папке проекта создайте файл bot.py (или любое другое имя) и вставьте следующий код:

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
)

# Токен вашего бота (замените на свой!)
TOKEN = '1234567890:ABCdefGHIjklMNOpqrsTUVwxyz'

# Обработчик команды /start
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Отправляет приветственное сообщение при команде /start"""
    user = update.effective_user
    await update.message.reply_text(
        f'Привет, {user.first_name}! \n\n'
        f'Я простой эхо-бот на Python Telegram Bot.\n'
        f'Отправь мне любое сообщение, и я его повторю.'
    )

# Обработчик текстовых сообщений (эхо)
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Повторяет полученное сообщение"""
    text = update.message.text
    await update.message.reply_text(f'Вы написали: {text}')

# Главная функция запуска бота
def main():
    """Точка входа в приложение"""
    # Создаём объект Application с токеном
    application = Application.builder().token(TOKEN).build()

    # Регистрируем обработчики команд и сообщений
    application.add_handler(CommandHandler("start", start))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

    # Запускаем polling (бот начинает слушать сообщения)
    print('Бот запущен! Нажмите Ctrl+C для остановки.')
    application.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == '__main__':
    main()

Шаг 2: Замените токен на свой

В строке TOKEN = '1234567890:...' вставьте токен, полученный от @BotFather.

Разбор кода: что делает каждая часть

Часть кода Объяснение
import telegram Импорт основной библиотеки python-telegram-bot
Application.builder() Создаёт объект приложения с вашим токеном (начиная с версии 20.x)
CommandHandler("/start", start) Регистрирует функцию start для обработки команды /start
MessageHandler(filters.TEXT, echo) Регистрирует функцию echo для всех текстовых сообщений (кроме команд)
application.run_polling() Запускает бота в режиме polling (постоянно проверяет новые сообщения)
async def start(...) Асинхронная функция-обработчик (python-telegram-bot v20+ использует async/await)

Запуск Telegram-бота: тестирование работы

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

python bot.py

Ожидаемый вывод в терминале:

Бот запущен! Нажмите Ctrl+C для остановки.
2025-12-01 12:00:00,123 - telegram.ext.Application - INFO - Application started

Шаг 2: Откройте диалог с ботом в Telegram

  1. Найдите бота по username (который вы указали в @BotFather)
  2. Нажмите кнопку «Start» внизу
  3. Отправьте команду /start

Ожидаемый ответ бота:

Привет, Ваше Имя!

Я простой эхо-бот на Python Telegram Bot.
Отправь мне любое сообщение, и я его повторю.

Шаг 3: Проверьте функцию эхо

Отправьте любое текстовое сообщение боту, например: Привет!

Бот должен ответить: Вы написали: Привет!

Остановка бота

Для остановки бота нажмите Ctrl + C в терминале.

Частые ошибки при установке python-telegram-bot и их решения

Ошибка 1: «ModuleNotFoundError: No module named ‘telegram'»

Причина: библиотека python-telegram-bot не установлена или установлена в другом окружении Python.

Решение:

# Убедитесь, что виртуальное окружение активировано
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Переустановите библиотеку
pip install python-telegram-bot --upgrade

Ошибка 2: «telegram.error.InvalidToken: Invalid token»

Причина: неправильный формат токена или токен скопирован с лишними символами.

Решение:

  • Проверьте, что токен скопирован полностью (формат: 123456:ABC-DEF...)
  • Убедитесь, что нет пробелов в начале/конце токена
  • Создайте нового бота через @BotFather и получите новый токен

Ошибка 3: «AttributeError: module ‘telegram’ has no attribute ‘ext'»

Причина: установлена устаревшая версия библиотеки или конфликт с другим пакетом telegram.

Решение:

# Удалите старые версии
pip uninstall telegram python-telegram-bot -y

# Установите актуальную версию
pip install python-telegram-bot==20.7

Ошибка 4: Бот не отвечает на сообщения

Возможные причины и решения:

  • Бот не запущен — убедитесь, что python bot.py выполнен и работает
  • Firewall блокирует — проверьте настройки брандмауэра (порт 443 должен быть открыт)
  • Неправильный username — проверьте, что открыли диалог с правильным ботом (через t.me/your_bot_username)

Следующие шаги: как развивать Telegram-бота на Python

Теперь, когда у вас работает базовый бот, вот направления для развития:

1. Добавить inline-кнопки

Кнопки делают бота интерактивным:

from telegram import InlineKeyboardButton, InlineKeyboardMarkup

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = [
        [InlineKeyboardButton("О боте", callback_data='about')],
        [InlineKeyboardButton("Помощь", callback_data='help')]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text('Выберите опцию:', reply_markup=reply_markup)

2. Интегрировать с базой данных

Для хранения данных пользователей используйте SQLite, PostgreSQL или MongoDB:

import sqlite3

# Создаём таблицу пользователей
conn = sqlite3.connect('bot_users.db')
cursor = conn.cursor()
cursor.execute('''CREATE TABLE IF NOT EXISTS users
                  (user_id INTEGER PRIMARY KEY, username TEXT)''')
conn.commit()

3. Подключить API и веб-сервисы

Боты могут делать запросы к внешним API (погода, курсы валют, новости):

import requests

async def weather(update: Update, context: ContextTypes.DEFAULT_TYPE):
    response = requests.get('https://api.openweathermap.org/data/2.5/weather?q=Moscow')
    data = response.json()
    await update.message.reply_text(f"Погода: {data['weather'][0]['description']}")

4. Запустить бота на сервере (VPS)

Для работы 24/7 разместите бота на облачном сервере:

  • Heroku — бесплатный тариф для начинающих
  • DigitalOcean — VPS от $5/мес
  • AWS / Google Cloud — профессиональные решения

5. Изучить продвинутые функции

  • Webhook вместо polling (для продакшена)
  • Приём платежей (интеграция с ЮKassa, Stripe)
  • Админ-панель для управления ботом
  • AI-интеграции (ChatGPT, Claude для умных ответов)

Часто задаваемые вопросы о python-telegram-bot

Какая версия python-telegram-bot актуальна сейчас?

На декабрь 2025 года актуальная версия — 20.7. Проверить последнюю версию можно на PyPI.

Чем отличается python-telegram-bot от aiogram?

python-telegram-bot — универсальная библиотека с поддержкой как sync, так и async кода. aiogram — только async, более современная архитектура, но меньше документации на русском. Для начинающих лучше python-telegram-bot.

Можно ли использовать python-telegram-bot в коммерческих проектах?

Да, библиотека распространяется под лицензией LGPLv3, которая разрешает коммерческое использование. Исходный код бота остаётся вашей собственностью.

Нужен ли платный хостинг для бота?

Для тестирования достаточно запускать бота на своём компьютере. Для продакшена (24/7 работа) нужен VPS или облачный сервер от $5/мес.

Как защитить токен бота от утечки?

Используйте переменные окружения или файл .env:

# Установите python-dotenv
pip install python-dotenv

# Создайте файл .env
TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# Загрузите в коде
from dotenv import load_dotenv
import os
load_dotenv()
TOKEN = os.getenv('TOKEN')

Важно: добавьте .env в .gitignore, чтобы не загружать токен на GitHub!

Нужен профессиональный Telegram-бот для бизнеса?

Если вы изучаете Python Telegram Bot для хобби или обучения — эта инструкция даст вам отличный старт. Но если вам нужен бот для бизнеса с интеграциями, CRM, AI-квалификацией лидов и автоматизацией продаж — мы поможем.

Opus Digital разрабатывает кастомные боты на Python:

  • ✅ Интеграция с любыми CRM (Битрикс24, AmoCRM, 1С)
  • ✅ AI-квалификация лидов через GPT-4
  • ✅ Мультиканальные боты (Telegram + VK + Max мессенджер)
  • ✅ Приём платежей, автоворонки, сложная бизнес-логика
  • ✅ Исходный код, документация, поддержка

Тарифы: от 15 000₽ (базовый бот) до 150 000₽ (полная автоматизация).
Срок: 3-21 день в зависимости от сложности.

Заказать бота для бизнеса

 

Мы используем cookie для улучшения работы сайта.
Продолжая использовать сайт, вы соглашаетесь с
политикой обработки данных.