раздел 02

Как работает Bot API

Telegram общается с вашим ботом через Bot API - это HTTP-интерфейс. Ваш код шлёт запросы на api.telegram.org, чтобы отправлять сообщения, и получает входящие события (их называют update). Каждый запрос подписан токеном бота.

Главный вопрос на старте: как код узнаёт о новых сообщениях. Есть два способа.

Polling vs webhook

Long polling
Бот сам периодически спрашивает Telegram: есть новые сообщения? Ничего настраивать не нужно, работает с локального компьютера без публичного адреса. Идеально для разработки и старта.
Webhook
Telegram сам шлёт каждое сообщение POST-запросом на ваш HTTPS-URL. Нужен сервер с доменом и SSL. Эффективнее и быстрее - выбор для продакшена.

Коротко: для первого бота и локальной разработки берите polling - он проще и не требует сервера. Когда дойдёте до деплоя на сервер с HTTPS, имеет смысл переключиться на webhook. Логика бота при этом не меняется, меняется только способ доставки сообщений.

Что бот умеет

Через Bot API бот может:

  • Отправлять и принимать текстовые сообщения.
  • Показывать кнопки: inline-кнопки под сообщением и reply-клавиатуру вместо обычной.
  • Принимать и отправлять файлы, фото, документы, голосовые, видео.
  • Реагировать на команды (сообщения, начинающиеся со слэша, например /start).
  • Редактировать и удалять свои сообщения, отправлять «печатает...».

Любое входящее событие приходит как update - объект с информацией о том, кто и что прислал. Библиотека разбирает update за вас и вызывает нужный обработчик.

Токен в .env

Код должен читать токен из переменной окружения, а не хранить в исходниках. Создайте файл .env:

BOT_TOKEN=123456789:AAExampleTokenReplaceWithYourOwn

И добавьте .env в .gitignore, чтобы он не попал в репозиторий. Как именно прочитать токен из окружения в коде - в следующем разделе.