Создать Telegram‑бота на Python

Пользовательский Telegram‑бот показывает фотографию кота на экране телефона

О чём эта статья

Быстрая инструкция по созданию Telegram‑бота на Python 3 с использованием python-telegram-bot и requests.
Полный рабочий пример, комментарии и исправления типичных ошибок.
Альтернативы (polling vs webhooks), варианты хостинга (локально, Raspberry Pi, облако).
Практические советы по безопасности, тестам и развёртыванию.

Почему стоит прочитать

Если вы хотите автоматизировать небольшие задачи в чатах, создать развлекательного бота или научиться основам Bot API, этот гид даст готовый минимальный проект и дорожную карту для дальнейшего развития.

Пререквизиты

Python 3.6+
Аккаунт Telegram и доступ к @BotFather
Базовые навыки работы с терминалом и текстовым редактором

Краткое определение: Bot API — это HTTP-интерфейс Telegram для управления ботами и отправки/получения сообщений.

Получение токена бота

В Telegram откройте чат с @BotFather.
Введите команду /newbot и следуйте подсказкам: задайте имя и username (заканчивается на “bot”).
@BotFather вернёт вам уникальный токен. Сохраните его — он нужен для доступа к Bot API.

Important: токен — секрет. Не выкладывайте его в публичные репозитории.

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

Откройте терминал и установите зависимости.

Для Windows (в командной строке):

pip install python-telegram-bot requests

Для macOS/Linux (в терминале):

pip3 install python-telegram-bot requests

Note: в некоторых системах предпочтительна группа виртуального окружения (venv) — используйте его для изоляции зависимостей.

Структура проекта

Создайте папку проекта, откройте редактор и добавьте файл main.py. В конце статьи есть чек‑лист для разработчика и тестов.

Полный пример кода (рабочая версия)

Ниже — минимальный, но исправленный пример. Обратите внимание: для корректного извлечения JSON из ответа requests мы используем .json(), а метод отправки фото принимает аргумент photo.

from telegram.ext import Updater, CommandHandler
import requests

def get_url():
    """Запрашивает случайную картинку кошки у TheCatAPI и возвращает URL."""
    resp = requests.get('https://api.thecatapi.com/v1/images/search', timeout=10)
    resp.raise_for_status()
    data = resp.json()
    if not data or not isinstance(data, list):
        raise ValueError('Некорректный ответ от TheCatAPI')
    return data[0].get('url')

def send_image(update, context):
    """Обработчик команды /meow: получает URL и отправляет фото в чат."""
    try:
        url = get_url()
        chat_id = update.effective_chat.id
        context.bot.send_photo(chat_id=chat_id, photo=url)
    except Exception as e:
        update.message.reply_text('Не удалось получить изображение. Попробуйте позже.')
        # В реальном приложении: логировать ошибку

def main():
    # Замените STRING_TOKEN на токен, который дал вам BotFather
    updater = Updater('1190888035:AAGeJ9316R95NqJLFefV5vQA-UL4np11V2c', use_context=True)
    dp = updater.dispatcher
    dp.add_handler(CommandHandler('meow', send_image))
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

Ключевые исправления и замечания:

requests.get(…).json() — чтобы получить объект JSON.
timeout и raise_for_status() — базовая защита от подвисшего запроса и HTTP‑ошибок.
Используем update.effective_chat.id и context.bot для лучшей совместимости с python-telegram-bot.

Как это работает — шаги

Бот получает команду /meow от пользователя.
Обработчик send_image вызывает get_url(), который запрашивает TheCatAPI.
Возвращает URL изображения и отправляет его с помощью Bot API.

Тестирование локально

Запустите main.py: python main.py (или python3 main.py).
В Telegram откройте чат с вашим ботом и отправьте /meow.
Если бот не отвечает — проверьте журнал терминала, ошибки сети и корректность токена.

Критерии приёмки:

При вводе /meow бот отправляет изображение кошки.
В случае ошибки бот информирует пользователя корректным сообщением.

Когда этот подход не подойдёт (примеры и ограничения)

Большая нагрузка: long‑polling плохо масштабируется для сотен тысяч пользователей.
Низкая задержка и интерактивность: webhooks предпочтительнее для мгновенной доставки и интеграции с HTTPS‑сервисами.
Безопасность: хранение токена в открытом виде — риск утечки.

Альтернативы: polling vs webhooks

Polling (как в примере): проще для начинающих, не требует HTTPS‑сервер. Подходит для прототипов и небольших ботов.
Webhooks: Telegram отправляет POST на ваш HTTPS‑endpoint. Требует домена и SSL, лучше для продакшена и масштабирования.

Мини‑шпаргалка при выборе:

Если хотите быстро прототипировать — polling.
Если бот публичный и ожидает высокую нагрузку — webhooks + облачный хостинг.

Развёртывание: варианты

Raspberry Pi (локальный сервер)
- Плюсы: низкая стоимость, полное управление.
- Минусы: стабильность сети и наличие публичного IP/динамический DNS.
VPS или облако (DigitalOcean, AWS EC2, Google Compute, Azure VM)
- Плюсы: контроль, гибкость, доступность.
- Минусы: платно, требует администрирования.
PaaS (Heroku, Render, Railway)
- Плюсы: простое деплоймент-решение, часто есть бесплатный уровень.
- Минусы: ограничения бесплатных планов, cold start.

Рекомендация: для небольших проектов используйте Render/Heroku/ Railway. Для долгоживущих сервисов — VPS или контейнеры в облаке.

Безопасность и лучшие практики

Храните токен в переменных окружения (ENV), не в коде.
Ограничьте логирование чувствительных данных.
Регулярно ротируйте токены (если подозреваете утечку).
Используйте версии библиотек с поддержкой безопасности.

Пример использования переменной окружения в main.py:

import os
TOKEN = os.getenv('TELEGRAM_BOT_TOKEN')
updater = Updater(TOKEN, use_context=True)

Role‑based чек‑листы

Разработчик:
- Запустить бота локально и проверить /meow.
- Добавить обработку ошибок и таймауты.
- Поместить токен в ENV.
Девопс:
- Выбрать среду для продакшена (PAAS/VPS).
- Настроить мониторинг и авто‑рестарт (systemd, supervisor или процесс‑менеджер).
Тестировщик:
- Проверить ответы при недоступном TheCatAPI.
- Проверить ограничение частоты (rate limiting) от API.

Тесты и приёмка

Примеры тест‑кейсов:

Успешный сценарий: /meow -> бот отправляет картинку.
Ошибка сети: симулировать отсутствие доступа к TheCatAPI -> бот корректно сообщает об ошибке.
Некорректный ответ API: бот не падает.

Мини‑методология разработки

Прототип: polling, локально.
Добавить логирование и обработку ошибок.
Перевести конфигурацию в ENV.
Тестирование (локально и в стейджинге).
Перевести на webhooks и деплой в продакшен при необходимости.

Советы по расширению функционала

Добавьте команды: /randombreed, /gif, /help.
Кешируйте полученные URL, чтобы снизить нагрузку на внешнее API.
Поддержка inline‑режима и клавиатур для интерактивности.

Частые ошибки и как их исправлять

“TypeError: ‘Response’ object is not subscriptable”: забыли вызвать .json().
Долгие блокирующие операции в обработчике: выносите тяжёлые запросы в отдельный поток/задачу или используйте ассинхронный подход.

Короткий глоссарий

BotFather — официальный бот Telegram для создания токенов.
polling — периодический опрос Telegram для получения обновлений.
webhook — механизм, при котором Telegram POST‑ит данные на ваш сервер.

Примеры расширений и шаблоны

Шаблон ответа при ошибке:

update.message.reply_text('Не удалось обработать запрос. Попробуйте позже.')

Пример кеширования с простым словарём (для уменьшения числа запросов к TheCatAPI):

_cache = {}

def get_url_cached():
    if 'url' in _cache:
        return _cache['url']
    url = get_url()
    _cache['url'] = url
    return url

Note: для реального кеша используйте redis/memcached с TTL.

Короткое объявление (для соцсетей / релиза)

Создал простого Telegram‑бота на Python, который по команде /meow присылает случайную картинку кота из TheCatAPI. Полный рабочий код, инструкции по хостингу и рекомендации по безопасности — в статье.

Итог — что взять с собой

Минимальный бот готов за 30–60 минут.
Для продакшена рассмотрите webhooks и безопасное хранение токенов.
Добавьте логирование, таймауты и обработку ошибок.

Summary:

Бот демонстрирует основные механики Bot API и внешний HTTP‑запрос к стороннему сервису.
Дальше можно развивать функционал: команды, inline, интеграции.

Important: не публикуйте секреты (токены) в открытых репозиториях.

Как создать простого Telegram‑бота, который присылает милых котиков