Telegram Bot API: getUpdates, вебхук и проверка бота

Если бот не получает обновления даже после этой инструкции, напишите в комментариях моего Telegram-канала: там я разбираю такие случаи.

Для разработки и отладки удобнее getUpdates: бот работает на ноутбуке без домена и сертификата. Для рабочего бота подходят вебхук или getUpdates с длинным опросом, а короткий опрос документация оставляет только для тестов. В обоих случаях Telegram хранит неполученные обновления до 24 часов и отдает их одинаковыми объектами Update.

Как устроен запрос

Каждый запрос к Bot API идет по HTTPS на адрес вида https://api.telegram.org/bot<токен>/<метод>. Подходят GET и POST, параметры передают в строке запроса, формой, в JSON или в multipart/form-data для файлов. Токен выдает @BotFather командой /newbot.

Проверить токен можно методом getMe. В ответе придет "ok":true и имя бота. При неверном токене Telegram вернет ошибку 401 Unauthorized.

curl https://api.telegram.org/bot<токен>/getMe

Если api.telegram.org из вашей сети не открывается, воспользуйтесь проверкой Telegram-бота. Она вызывает getMe, getUpdates, getWebhookInfo, setWebhook и deleteWebhook с нашего сервера, поэтому VPN не нужен. Токен уходит в один запрос к Telegram и не сохраняется ни в базе, ни в журналах.

getUpdates и подтверждение обновлений

Метод getUpdates отдает накопленные обновления: новые сообщения, нажатия кнопок, вступления в чаты.

curl "https://api.telegram.org/bot<токен>/getUpdates?offset=0&timeout=30"

Обновление считается подтвержденным, когда вы вызываете getUpdates с offset больше его update_id. Пока этого нет, те же обновления приходят снова. Поэтому после каждого ответа берите последний update_id, прибавляйте единицу и передавайте в следующий запрос.

Параметр limit задает, сколько обновлений придет за раз, от 1 до 100, по умолчанию 100. timeout больше нуля включает длинный опрос, и Telegram держит соединение, пока не появится обновление. С timeout=0 опрос короткий и подходит только для проверки.

Если бота пишет ИИ-агент, ему пригодится Telegram API MCP: сервер отправляет сообщения и посты от имени бота через Bot API. Для работы с личным аккаунтом, а не с ботом, есть Telegram MCP Server на Telethon.

Как поставить вебхук

С вебхуком Telegram сам отправляет каждое обновление на ваш адрес. Адрес задает метод setWebhook, нужен HTTPS на одном из портов 443, 80, 88 или 8443.

curl -F "url=https://example.ru/tg" -F "secret_token=my_secret_42" https://api.telegram.org/bot<токен>/setWebhook

Параметр secret_token отличает запросы Telegram от чужих. Telegram кладет его в заголовок X-Telegram-Bot-Api-Secret-Token каждого запроса, и сервер бота должен сверять этот заголовок. max_connections ограничивает число одновременных соединений к вашему серверу, от 1 до 100, по умолчанию 40. Если ваш сервер ответит кодом не из группы 2XX, Telegram повторит запрос, а после нескольких неудачных попыток перестанет.

Как проверить, что вебхук работает

Метод getWebhookInfo показывает текущий адрес, число обновлений в очереди в поле pending_update_count и последнюю ошибку доставки в полях last_error_message и last_error_date. Если бот молчит, начинать стоит с него.

curl https://api.telegram.org/bot<токен>/getWebhookInfo

Пустое поле url значит, что вебхука нет и обновления можно забирать через getUpdates. Растущий pending_update_count вместе с ошибкой означает, что Telegram не может достучаться до вашего адреса.

Почему getUpdates пустой

Причин обычно три. Первая причина в вебхуке. Пока он стоит, getUpdates не работает, и Telegram отвечает ошибкой 409 Conflict. Метод deleteWebhook снимает вебхук, после чего обновления снова можно забирать вручную. Параметр drop_pending_updates=true при этом выбросит накопленную очередь.

Вторая причина в самом боте. Если его код уже работает на сервере и опрашивает getUpdates, он подтверждает обновления раньше, чем вы их увидите. Два одновременных опроса тоже дают ошибку 409 с текстом о том, что запрос прервал другой getUpdates.

Третья причина в фильтре. По умолчанию бот не получает обновления chat_member, message_reaction и message_reaction_count, их нужно явно перечислить в параметре allowed_updates. Если боту за последние 24 часа никто не писал, очередь тоже будет пустой.

Свой сервер Bot API

Исходный код сервера Bot API открыт в репозитории tdlib/telegram-bot-api, 4474 ★ репозитория. На своем сервере бот загружает файлы до 2000 МБ, скачивает их без ограничения размера и принимает вебхук по обычному HTTP на любом порту, поэтому свой сервер ставят владельцы ботов, которые работают с видео и архивами.

Права и безопасность токена

Токен дает полный контроль над ботом. Тот, у кого он есть, читает обновления, отправляет сообщения и меняет вебхук. Храните токен в переменных окружения и не вставляйте в код. Утекший токен отзывают командой /revoke в @BotFather. Старый сразу перестает работать.

Бот и ИИ-агент

Управлять ботом из Claude Code или Cursor можно через MCP. Telegram API MCP дает агенту 185 методов Bot API, уровень риска у него высокий. Агент сможет публиковать и удалять сообщения, банить участников и вызывать платежные методы от имени бота. Автоматической установки у этого сервера нет, пакета в npm на 30 сентября 2026 года тоже нет, поэтому сервер собирают из репозитория по инструкции на карточке. Для первого запуска выпустите отдельного тестового бота.

Переписываться с самим агентом из Telegram позволяет Claude-to-IM, 2882 ★ репозитория. Скилл поднимает фоновый процесс и хранит токены ботов, поэтому риск у него тоже высокий. Каждый вызов инструмента агентом нужно подтвердить кнопкой в чате, а доступ ограничивается списком пользователей.

npx skillfoxx add skills/claude-to-im

Перед установкой CLI напечатает обе причины высокого риска и спросит подтверждение в терминале.