Telegram getUpdates и setWebhook конфликтуют: безопасный runbook для переключения

У Telegram Bot API есть простое правило: один и тот же бот не должен одновременно получать updates через polling getUpdates и push-доставку setWebhook. Если после деплоя сообщения не приходят, сначала проверьте, какой receiver сейчас активен. Затем либо удалите webhook и вернитесь к polling, либо остановите polling worker и настройте webhook. Официальная документация Telegram также говорит, что pending updates хранятся временно, поэтому переключение лучше делать по runbook, а не наугад.

Главное

• getUpdates и setWebhook — два официальных режима доставки Bot API, а не два параллельных слоя.
• Перед изменениями вызовите getWebhookInfo: он покажет, задан ли webhook URL.
• При возврате к polling сначала вызовите deleteWebhook и решите, можно ли безопасно использовать drop_pending_updates.
• Если вы еще выбираете путь приема сообщений, начните с сравнения Telegram Bot API webhook vs unified inbound webhook.
• Если путаница в учетных данных, сначала прочитайте Telegram API ID/API hash vs bot token.

Что говорит официальный контур

Документация Telegram Bot API описывает два способа получения updates: getUpdates, когда ваш код делает long polling, и webhook, когда Telegram отправляет HTTPS-запросы на ваш endpoint. Там же указано, что getUpdates не будет работать, пока настроен outgoing webhook; для возврата к polling используется deleteWebhook.

Симптом	Возможное состояние	Первая проверка
Polling ничего не получает	Webhook URL все еще задан	getWebhookInfo
Webhook endpoint не получает запросов	Старый polling worker не остановлен или webhook настроен неверно	Остановить worker и проверить
Внутренняя очередь дает дубли или пропуски	Несколько инстансов обрабатывают один поток	Назначить одного владельца
После переключения пришел старый тестовый поток	Pending updates сохранены	Решить: обработать или удалить

Шаг 1: проверьте текущий receiver

Храните BOT_TOKEN в переменной окружения и не пишите его в логи:

curl "https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo"

Если url в ответе не пустой, webhook все еще настроен. Если url пустой, Bot API webhook не активен, и getUpdates может быть рабочим путем приема.

Шаг 2: переключение с webhook на getUpdates

Сначала удалите webhook:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/deleteWebhook" \
  -d "drop_pending_updates=false"

Для реальных обращений поддержки обычно выбирают false: сообщения нужно сохранить и обработать одним polling worker идемпотентно. true подходит только для одноразового тестового backlog или осознанного чистого переключения.

Затем запустите ровно один polling worker и продвигайте offset после каждого ответа getUpdates:

curl "https://api.telegram.org/bot$BOT_TOKEN/getUpdates?timeout=30"

Шаг 3: переключение с getUpdates на setWebhook

Сначала остановите polling worker. Затем задайте URL, которым владеет ваш production-сервис:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
  -d "url=https://support.example.com/telegram/bot-webhook"

Receiver должен отвечать быстро: сохраните Telegram update, затем запускайте CRM, AI-классификацию или распределение операторов асинхронно. Это тот же принцип store-first, что и в webhook-first inbound integration checklist, хотя Telegram Update и event schema UnifyPort отличаются.

Когда лучше unified inbound webhook

Этот runbook исправляет прием updates у Telegram-бота. Он не превращает бота в inbox обычного Telegram-аккаунта и не нормализует WhatsApp, LINE, TikTok, Zalo или X.

Если вашей команде нужен общий event layer для поддержки, создайте webhook в UnifyPort. Глубокая документация: Create webhook endpoint. Укажите HTTPS url, status: "active", подпишитесь на message.received или ["*"], а для проверки подписи задайте signing_secret.

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": { "id": "3003", "direction": "inbound", "sent_at": "2026-06-08T12:37:00Z", "text": "Can you check my order?" },
    "event": { "kind": "message_received" }
  }
}

Используйте официальный Bot API, если пользователь должен общаться именно с ботом и вам нужен объект Telegram Update. Используйте unofficial interface UnifyPort, если задача — inbound intake от подключенного аккаунта или единая очередь нескольких платформ.

FAQ

Можно ли использовать getUpdates и setWebhook одновременно?

Нет. Telegram описывает их как взаимоисключающие способы получения updates для Bot API bot. Удалите webhook перед polling или остановите polling перед настройкой webhook.

Нужно ли ставить drop_pending_updates=true?

Только если pending updates можно потерять. Для production-поддержки лучше сохранить поток и обработать его идемпотентно.

Это подключение обычного Telegram-аккаунта?

Нет. Bot API использует bot token. Подключенный Telegram-аккаунт через UnifyPort получает стандартизированные события message.received.

Sources checked on 2026-09-09

• Telegram Bot API getUpdates: https://core.telegram.org/bots/api#getupdates
• Telegram Bot API setWebhook: https://core.telegram.org/bots/api#setwebhook
• Telegram Bot API deleteWebhook: https://core.telegram.org/bots/api#deletewebhook
• Telegram webhook guide: https://core.telegram.org/bots/webhooks
• UnifyPort Create webhook endpoint