Telegram Bot API: как забрать сообщения в свою систему

Long polling или вебхук: как Telegram решает, кому и когда отдавать сообщения

Telegram отдаёт обновления боту одним из двух способов, и это не вопрос вкуса: методы взаимоисключающие на уровне API. Первый — long polling через метод getUpdates: бот сам раз за разом спрашивает сервер, есть что новое, передавая offset (id последнего полученного обновления), limit (от 1 до 100, по умолчанию 100) и timeout в секундах (по умолчанию 0). Второй — вебхук через setWebhook: Telegram сам присылает POST-запрос на ваш HTTPS-адрес при каждом новом событии. Если вебхук уже установлен, вызов getUpdates вернёт ошибку 409 Conflict с текстом «can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first» — Telegram не станет одновременно пушить и отдавать по запросу.

Структура самого обновления одна и та же в обоих случаях: объект Update с полем update_id и ровно одним из смысловых полей — message, edited_message, channel_post, edited_channel_post, callback_query, inline_query, my_chat_member и другими. Поля взаимоисключающие: пришло одно — остальные отсутствуют, и разбор на своей стороне сводится к проверке, какое поле не пусто. Разработчик обычно ждёт единый формат «сообщение», а получает объект, форма которого меняется в зависимости от типа события — это первое, на чём спотыкаются при интеграции с CRM.

Для продакшена, где сообщения нужно отдавать в CRM без задержки, вебхук почти всегда лучше: не нужно держать процесс, который бесконечно опрашивает Telegram, а данные приходят пуш-запросом сразу, как только событие случилось. Long polling остаётся удобным для разработки и для сред без белого IP или устойчивого HTTPS — например, для локальной отладки бота.

Настройка вебхука: секретный токен, порты и подсети Telegram

Метод setWebhook принимает адрес url (обязательно HTTPS), необязательный certificate для самоподписанного сертификата, ip_address для фиксации адреса, max_connections (от 1 до 100, по умолчанию 40), список allowed_updates, флаг drop_pending_updates и secret_token длиной от 1 до 256 символов, где допустимы только латиница, цифры, знаки подчёркивания и дефис.

Telegram стучится на вебхук только с двух подсетей — 149.154.160.0/20 и 91.108.4.0/22 — и только на порты 443, 80, 88 или 8443, при этом соединение всегда идёт по TLS независимо от порта. Если фильтруете входящие запросы по IP, держите в уме собственную оговорку Telegram: диапазон адресов может измениться, и документацию стоит перепроверять, а не зашивать список раз и навсегда.

secret_token — фактически единственный слой аутентификации входящего запроса помимо того, что адрес вебхука не публичен. Telegram передаёт его значение в заголовке `X-Telegram-Bot-Api-Secret-Token`, и сверять этот заголовок на своей стороне обязательно: URL вебхука может утечь в логи прокси или в переменные окружения CI, и без проверки токена кто угодно, узнавший адрес, сможет слать вам поддельные обновления.

Установить вебхук с токеном можно одним запросом:

Если за вебхуком стоит обычный реверс-прокси с сертификатом от доверенного центра сертификации, параметр certificate не нужен вовсе — большинство интеграций через CRM в него не упираются. Он нужен только тем, кто поднимает TLS-терминацию сам и подписывает сертификат собственным ключом.

Что происходит, когда вебхук падает — и как это увидеть, не дожидаясь жалобы

Официальная документация не публикует алгоритм и тайминги повторных попыток доставки вебхука — это то самое место, где она молчит. Подтверждено другое: непринятые обновления не пропадают сразу, а накапливаются, и это видно через getWebhookInfo. Объект WebhookInfo отдаёт url, has_custom_certificate, pending_update_count, ip_address, last_error_date и last_error_message, last_synchronization_error_date и текущие max_connections с allowed_updates.

На практике это единственный честный способ понять, что вебхук сломан, не дожидаясь жалобы от отдела продаж: растущий pending_update_count и свежая дата в last_error_date — сигнал проверять эндпоинт прямо сейчас. Полагаться на то, что Telegram будет пытаться доставить обновление сколь угодно долго, нельзя — точного SLA документация не даёт, и рассчитывать стоит на собственный мониторинг, а не на терпение чужого сервера.

Отдельная ловушка — таймаут ответа. Если обработчик вебхука делает синхронную работу до того, как ответить 200 OK, при росте нагрузки время ответа растёт вместе с ней, и Telegram начинает видеть это как сбой доставки. Паттерн один и тот же для всех push-вебхуков: подтвердить приём немедленно, обработку вынести в фон.

Лимиты Telegram: что говорит документация и где она действительно молчит

В отличие от версии этой статьи, где утверждалось обратное: лимит на один чат Telegram называет прямо, а не оставляет догадкам сообщества. Bots FAQ (раздел про попадание в лимиты, проверено 08.09.2026) формулирует это дословно: «In a single chat, avoid sending more than one message per second» — не больше одного сообщения в секунду в одном чате, кратковременные всплески допустимы, но за порогом начинаются 429.

Paid broadcasts включаются в @BotFather и имеют смысл только при систематической легитимной рассылке подписчикам на объёме, где 30 сообщений в секунду становятся узким местом, — для разовых уведомлений это избыточно.

Что документация действительно не раскрывает: как растёт время ожидания при повторных нарушениях и сколько по факту действует ограничение после серии 429. Наружу отдаётся только текущее значение parameters.retry_after в конкретном ответе — алгоритм, который стоит за этим числом, Telegram не публикует, и рассчитывать на предсказуемое поведение при систематическом превышении нельзя.

Разлогин и бан: что Telegram сообщает сам, а что нужно выяснять отправкой

У Telegram нет отдельного события «пользователь заблокировал бота». Узнать об этом можно только постфактум: при попытке отправить сообщение API вернёт 403 Forbidden с описанием вроде «bot was blocked by the user». Push-уведомления заранее не будет — если в CRM висит адресат, которому давно не доходят сообщения, единственный способ это выяснить — сама попытка отправки и разбор кода ошибки.

Для групп и каналов честный сигнал есть: обновление my_chat_member приходит, когда меняется статус самого бота — его добавили, исключили, повысили до администратора или понизили. Это единственный по-настоящему проактивный способ узнать о разрыве, который даёт сам Telegram, и в CRM его стоит обрабатывать отдельно от обычных сообщений.

Как то же самое устроено у ВКонтакте, Avito, HeadHunter и MAX

Когда в одну систему заводят не только Telegram, разница в схемах подтверждения и авторизации становится отдельной статьёй расходов на разработку — у каждой площадки она своя.

Данные по Telegram и MAX в таблице проверены напрямую по документации 08.09.2026. Метод groups.getCallbackConfirmationCode ВКонтакте подтверждён SDK и трекером задач VKCOM, но страница dev.vk.com была недоступна для прямой проверки на момент публикации — сверьте её самостоятельно перед интеграцией. Тайм-аут Avito намеренно дан с оговоркой по той же причине: не нашли способа открыть первоисточник напрямую, а выдавать чужой пересказ за проверенный факт — то, чего эта статья как раз старается не делать.

Как проверить вебхук за пять запросов, без строчки серверного кода

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

1. Посмотреть текущее состояниеcurl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo" — смотрите на url, pending_update_count и last_error_message.
2. Сбросить очередь при необходимостиcurl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true" — удаляет вебхук и накопленные обновления.
3. Установить вебхук заново с secret_tokenТот же запрос, что и в разделе про настройку — с параметрами url и secret_token.
4. Проверить заголовок на своей сторонеНа каждый входящий POST сверяйте значение X-Telegram-Bot-Api-Secret-Token с тем, что задали при установке — иначе тело запроса можно подделать, зная только адрес.
5. Отправить тестовое сообщение и перепроверитьНапишите боту в личку и снова вызовите getWebhookInfo: pending_update_count должен вернуться к нулю, а last_error_date — не обновляться свежей отметкой.

• Эндпоинт отвечает 200 OK быстро, обработка вынесена в фон
• secret_token проверяется на каждом входящем запросе, а не только при первой настройке
• getWebhookInfo вызывается по расписанию, а не только при жалобе на пропавшие сообщения
• Сертификат выпущен доверенным центром — параметр certificate не используется без нужды
• IP входящих запросов, если фильтруете, входят в 149.154.160.0/20 и 91.108.4.0/22

Частые вопросы