Telegram Bot API: getUpdates и webhook

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

• Поддерживаются методы GET и POST. Параметры можно передать в строке запроса, как application/x-www-form-urlencoded, как application/json (кроме загрузки файлов) и как multipart/form-data (для файлов).
• Ответ — JSON-объект с логическим полем ok. Если ok равно true, результат лежит в поле result. Если запрос не удался, ok равно false, а причину объясняют поля description и error_code.
• Входящее событие называется Update. У него есть update_id и ровно одно из необязательных полей: message, edited_message, channel_post, callback_query, pre_checkout_query и другие.

Способ 1. getUpdates — длинный опрос

Программа сама спрашивает Telegram о новых событиях. Публичный адрес не нужен, поэтому так проще начать и отлаживать бота на своём компьютере.

Параметры метода:

• offset — с какого update_id вернуть события. Передавайте update_id последнего полученного события плюс один.
• limit — сколько событий вернуть за раз: от 1 до 100, по умолчанию 100.
• timeout — сколько секунд Telegram держит запрос открытым, если новых событий нет. По умолчанию 0; для длинного опроса задайте положительное число, например 30.
• allowed_updates — список нужных типов событий, например ["message", "callback_query"]. Пустой список означает все типы, кроме chat_member, message_reaction и message_reaction_count. Если параметр не указан, действует прежняя настройка. Фильтр не касается событий, созданных до вызова, поэтому ненужные могут прийти ещё какое-то время.

Пример запроса: curl "https://api.telegram.org/bot<ТОКЕН>/getUpdates?timeout=30"

Как работает подтверждение: событие считается полученным, когда вы вызвали getUpdates с offset больше его update_id. До этого Telegram продолжает отдавать его снова. Хранит он неподтверждённые события не дольше 24 часов. Идентификаторы растут по порядку, и по ним легко пропускать повторы.

Следующий запрос после события с update_id 123456: curl "https://api.telegram.org/bot<ТОКЕН>/getUpdates?offset=123457&timeout=30"

Способ 2. setWebhook — Telegram присылает события сам

Вы указываете адрес, и на каждое событие Telegram отправляет туда HTTPS POST-запрос с Update в теле.

• url — обязательный параметр, адрес вашего сервера с HTTPS.
• Порты для webhook: 443, 80, 88 и 8443.
• secret_token — необязательная строка из 1–256 символов (латинские буквы, цифры, _ и -). Если она задана, Telegram добавляет в каждый запрос заголовок X-Telegram-Bot-Api-Secret-Token с этим значением. Сравнивайте его на своей стороне, чтобы убедиться, что запрос пришёл от вашей настройки, а не от постороннего.
• max_connections — число одновременных соединений от 1 до 100, по умолчанию 40.
• allowed_updates — список типов событий, как у getUpdates.
• drop_pending_updates — выбросить накопленные события.
• certificate — публичный сертификат, если используется самоподписанный.

Пример: curl "https://api.telegram.org/bot<ТОКЕН>/setWebhook?url=https://example.com/telegram&secret_token=my_secret_123"

Ваш сервер должен отвечать кодом HTTP 2xx. На любой другой ответ Telegram повторяет запрос и через разумное число попыток сдаётся.

Чтобы вернуться к опросу, вызовите deleteWebhook. Состояние webhook показывает getWebhookInfo: в ответе есть pending_update_count (сколько событий ждёт доставки), last_error_date и last_error_message (когда и почему доставка не удалась).

Частые ошибки

• Webhook и getUpdates одновременно. Пока webhook задан, getUpdates не работает. Вызовите deleteWebhook.
• Не сдвинут offset. Если каждый раз передавать один и тот же offset или не передавать его, бот снова и снова получит одни и те же события.
• Недоступный адрес webhook. Адрес должен быть доступен из интернета по HTTPS на одном из четырёх портов. Если события не приходят, откройте getWebhookInfo и прочитайте last_error_message.
• Нужные события не приходят. chat_member, message_reaction и message_reaction_count по умолчанию не присылаются: перечислите их в allowed_updates. Помните, что при незаданном параметре действует прежняя настройка.
• Токен в коде. Никогда не выкладывайте токен в репозиторий: как хранить токен и что делать при утечке.

Что дальше

Когда бот принимает события, остаётся ответить на них. Если бот будет продавать цифровые товары, подключите оплату: оплата звёздами в боте. Нужно, чтобы программа покупала звёзды или Premium для своих пользователей? Для этого есть API бота Shiba Bank, его описание — в документации API.

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