Long polling или webhook для Telegram-бота

Long polling подходит небольшому постоянно работающему боту, в том числе скачиваемому примеру. Webhook удобен, когда уже есть публичный HTTP backend или нужны очередь и несколько обработчиков. Ни один способ сам по себе не предотвращает повторные платные вызовы: дубликаты и сбои должен учитывать код.

Сопоставьте способ доставки со своей задачей

При polling запрос ожидает новые сообщения, а не опрашивает API каждую миллисекунду. Webhook не гарантирует меньшую задержку полного AI-ответа: остаются очередь, генерация и отправка сообщения. Одновременно использовать оба способа получения обновлений с одним токеном нельзя.

Почему в примере выбран polling

В боте нет HTTP-сервера, webhook route или настройки домена. Установка Caddy не превращает его в webhook-приложение. Запускайте только одну копию с одним токеном, включая локальные проверки с ноутбука. Файловая блокировка защищает одну базу от двух процессов, но не остановит второй VPS с другой базой и тем же токеном.

Перед платной попыткой бот сохраняет обработанную позицию. При обычном restart он не повторяет этот запрос автоматически, но после аварии ответ может потеряться. Перед изменением поведения прочитайте руководство по состоянию.

Проверить webhook можно без вывода потенциально секретного URL. Выполните в настроенном каталоге Compose:

docker compose run --rm -T bot python - <<'PYCODE'
from bot import Config, Telegram
info = Telegram(Config.from_env().telegram_token).call('getWebhookInfo')
print({
    'webhook_configured': bool(info.get('url')),
    'pending_update_count': info.get('pending_update_count'),
    'has_delivery_error': bool(info.get('last_error_date')),
})
PYCODE

Это запрос метаданных Telegram, не inference. Если webhook настроен, сначала выясните, какое приложение его использует. Остановите старого получателя перед осознанным переключением. Не удаляйте неизвестный webhook только ради запуска инструкции. Удаление webhook и отбрасывание ожидающих сообщений — разные решения. Telegram хранит недоставленные обновления ограниченное время и не заменяет бэкап.

Что требуется от настоящего webhook backend

Публичный HTTPS endpoint должен проверить X-Telegram-Bot-Api-Secret-Token, структуру обновления, дубликат по update_id и надёжно принять задание до успешного HTTP-ответа. Не подтверждайте получение, пока оно нигде не сохранено. Долгую генерацию отделяйте от HTTP-запроса: отдельный worker обращается к модели и отправляет сообщение.

Секретный заголовок подтверждает доставку от Telegram, но не права пользователя. По-прежнему нужны проверки личного чата и ID, постоянный счётчик попыток и правила для неопределённого результата платного запроса. Повтор задания после таймаута может привести к двойному списанию. Наш polling-пример не содержит webhook-сервера с очередью.

Mini App — другое соединение

Mini App — веб-страница, которую открывает Telegram-клиент. Браузер обращается к вашему backend по HTTPS. Кнопку Mini App можно добавить в меню бота, который продолжает получать сообщения через polling. Проверка initData и секретный заголовок webhook защищают разные запросы и не заменяют друг друга.

Начните со схемы, которую сможете обслуживать. Для готового бота используйте Docker Compose, при конфликте — диагностику. Источники: getUpdates, setWebhook.