Создать Telegram‑бота для фото котиков

Иллюстрация: интерфейс и значки Telegram‑ботов

Что вам понадобится

Установленный Python 3 (рекомендуется 3.7+). 1‑строчное определение: Python — язык программирования, на котором мы пишем бота.
Учетная запись Telegram и доступ к @BotFather для создания токена.
Библиотеки python-telegram-bot и requests.
Опционально: аккаунт на платформе хостинга (Heroku, AWS, Google Cloud, Azure) или Raspberry Pi для постоянной работы.

Важно: не публикуйте токен вашего бота — храните его в переменных окружения / секретном хранилище.

Основная идея (умственная модель)

Бот получает команду от пользователя (/meow).
Бот делает HTTP‑запрос к TheCatAPI и получает JSON с URL картинки.
Бот отправляет картинку в чат через Telegram Bot API.

Эта модель «команда → внешний API → ответ пользователю» применима к любым ботам, которые возвращают контент из внешних источников.

Создание бота в Telegram и получение токена

Откройте чат с @BotFather в Telegram.
Введите команду /newbot и следуйте подсказкам: задайте имя и username (username должен оканчиваться на “bot”).
Сохраните токен (строка вида 123456:ABC-DEF…) — он понадобится для кода.

Важно: если токен случайно попал в репозиторий — немедленно удалите и сгенерируйте новый в BotFather.

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

Windows (cmd):

pip install python-telegram-bot
pip install requests

macOS / Linux (Terminal):

pip3 install python-telegram-bot
pip3 install requests

Если вы используете виртуальное окружение (рекомендуется), создайте и активируйте его перед установкой.

Полный код бота (корректный и готовый к использованию)

Сохраните файл как main.py. В коде комментарии на русском для простоты понимания.

from telegram.ext import Updater, CommandHandler
import requests
import os

# Получаем URL случайной картинки кота из TheCatAPI
def get_url():
    response = requests.get('https://api.thecatapi.com/v1/images/search')
    data = response.json()  # API возвращает список словарей
    url = data[0]['url']
    return url

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

def main():
    # Рекомендуется хранить токен в переменной окружения TELEGRAM_BOT_TOKEN
    token = os.environ.get('TELEGRAM_BOT_TOKEN')
    if not token:
        print('Введите TELEGRAM_BOT_TOKEN в переменных окружения и перезапустите скрипт.')
        return

    updater = Updater(token)
    # Регистрируем обработчик команды /meow
    updater.dispatcher.add_handler(CommandHandler('meow', send_image))
    # Запускаем опрос Telegram (polling)
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

Примечания:

В продакшне храните токен в переменных окружения или секретах CI/CD, а не в коде.
Используем .json() у ответа requests, иначе попытка обработать объект Response как список приведёт к ошибке.

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

Пользователь отправляет /meow.
python-telegram-bot вызывает send_image.
send_image вызывает get_url, который делает GET‑запрос к https://api.thecatapi.com/v1/images/search.
Полученный JSON парсится, берётся первый элемент, из него — ключ ‘url’.
Бот отправляет изображение через context.bot.send_photo.

Отладка и распространённые ошибки

Ошибка: “No token provided” — проверьте переменную окружения TELEGRAM_BOT_TOKEN.
Ошибка при парсинге JSON — проверьте сетевое подключение и статус ответа (response.status_code).
Бот не отвечает при закрытом main.py — это ожидаемо, пока бот не развернут на сервере.

Важное: добавьте логирование ошибок (или отправку в внешний лог‑сервис), если бот работает длительное время.

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

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

При вводе команды /meow бот отвечает сообщением с изображением.
При недоступности TheCatAPI бот возвращает дружелюбное сообщение об ошибке.
Бот корректно работает с группами и личными чатами (проверить в обоих контекстах).

Тестовые случаи:

Отправить /meow в личный чат — ожидать фото.
Отправить /meow в групповой чат — ожидать фото.
Отключить интернет или заблокировать домен thecatapi.com — бот должен ответить сообщением об ошибке.
Повторить команду много раз (20–50 запросов подряд) и убедиться, что API корректно отвечает (проверьте лимиты).

Развёртывание: варианты и рекомендации

Локально (для разработки)
- Просто запускайте python main.py. Подойдёт для тестирования и разработки.
Raspberry Pi (малозатратный хостинг дома)
- Удобно, если вы хотите всегда держать бот в сети без использования облака.
- Настройте автозапуск systemd, UPS по необходимости.
Облако (Heroku, AWS, GCP, Azure)
- Современный выбор для стабильной работы и масштабирования.
- Heroku: прост в настройке для prototyping (используйте Procfile и переменные окружения).
- AWS / GCP / Azure: выбирайте контейнер (Docker) или serverless (Cloud Run, Lambda + API Gateway) по потребностям.

Мини‑руководство для Heroku (SOP):

Создайте аккаунт на Heroku и новый приложение.
Добавьте Procfile с содержимым: web: python main.py
Установите переменную TELEGRAM_BOT_TOKEN в настройках приложения.
Разверните код (git push heroku main).
Убедитесь, что приложение запущено и проверяйте логи (heroku logs –tail).

Совет: если используете polling, убедитесь, что процесс постоянно запущен. Альтернатива — Webhook: Telegram будет отправлять запросы на ваш HTTPS endpoint (подходит для облачных хостингов с публичным доменом).

Альтернативные подходы

Вариант с Webhook: вместо polling настроить HTTPS endpoint и регистрировать webhook у Telegram. Подходит при высокой нагрузке и для многих одновременных ботов.
Использовать библиотеку aiogram (асинхронная) для лучшей производительности при большом потоке сообщений.
Кэширование URL картинок для уменьшения числа запросов к TheCatAPI.

Когда подход с polling не подходит:

Ваш хост не гарантирует 24/7 uptime.
Нужны мгновенные ответы при высокой нагрузке — лучше webhook.

Безопасность и приватность

Не храните токен в публичных репозиториях.
Ограничьте доступ к серверу, где запущен бот (SSH, firewall).
Если бот собирает пользовательские данные, опишите это в политике конфиденциальности и соблюдайте локальные требования (например, GDPR для ЕС).
TheCatAPI может иметь свои правила использования и лимиты — проверьте документацию перед массовыми запросами.

Чек‑лист по ролям

Разработчик:

Создать проект и виртуальное окружение.
Реализовать обработчик /meow.
Добавить обработку ошибок и логирование.

Оператор/DevOps:

Настроить переменные окружения для токена.
Настроить автозапуск (systemd / service) или процесс в облаке.
Мониторить логи и использование API.

Модератор/Владелец бота:

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

Риски и mitigations

Ограничения API (rate limits): внедрите кэширование и повторные попытки с экспоненциальной задержкой.
Утечка токена: ротация токенов и использование секретного хранилища.
Непредвиденные ошибки в коде: мониторинг ошибок и автоматический перезапуск.

Примеры расширений (идеи для развития бота)

Команда /breed — искать фото определённой породы (если TheCatAPI поддерживает breed_id).
Команда /random_with_caption — отправлять подпись с мемом или фактом о котах.
Интеграция с базой данных для сохранения любимых изображений пользователей.

FAQ

Как заменить токен в коде?

Создайте переменную окружения TELEGRAMBOT_TOKEN и запустите: export TELEGRAM_BOT_TOKEN=”ваштокен” (Linux/macOS) или setx TELEGRAMBOT_TOKEN “ваштокен” (Windows).

Нужно ли регистрироваться в TheCatAPI?

Для простых запросов регистрация может не потребоваться, но при большом объёме запросов лучше получить API‑ключ и ознакомиться с условиями использования.

Чем polling отличается от webhook?

Polling — бот сам регулярно проверяет обновления у Telegram. Webhook — Telegram отправляет обновления на ваш HTTPS endpoint. Webhook обычно эффективнее при масштабировании.

Краткая сводка

За 30–60 минут можно собрать работающего Telegram‑бота, отправляющего фото котиков.
Используйте переменные окружения для секретов, логируйте ошибки и выбирайте способ развёртывания в зависимости от нагрузки.
Для продакшна рассмотрите webhook, контейнеризацию и мониторинг.

Ключевые действия прямо сейчас: создайте бота в @BotFather, сохраните токен, подготовьте environment и запустите main.py.

Если хотите, могу сгенерировать готовый Procfile и пример Dockerfile для развёртывания, а также шаблон systemd‑сервиса для Raspberry Pi.