Настройка вебхуков
Все методы вызываются по адресу https://api.kodari.ru/msg/bot.php?method=ИМЯ_МЕТОДА. Передавайте токен бота в Authorization: Bearer .... Для setWebhook и deleteWebhook нужен POST; параметры можно передать JSON-объектом или обычной формой.
setWebhook
Сохраняет адрес получателя. Успешный результат: {"ok": true, "result": true}.
| Параметр | Тип | Поведение |
|---|---|---|
url | string | Обязательный HTTPS-адрес, не более 2048 байт, порт 443, публичный IPv4. Пустая строка отключает вебхук |
secret_token | string | Необязательный секрет: 1–256 латинских букв, цифр, _ или -. Передаётся в X-Shlyaps-Bot-Api-Secret-Token. Если не передан при повторной настройке, прежний секрет удаляется |
allowed_updates | array of string | Типы событий для вебхука. Пустой массив означает все типы. При отсутствии параметра сохраняется прежний список |
drop_pending_updates | bool | По умолчанию false. При true ожидающая очередь удаляется |
Поддерживаются message, edited_message, message_reaction, callback_query, forum_topic_created, forum_topic_edited, forum_topic_closed, forum_topic_reopened, forum_topic_deleted, forum_status_changed. Фильтр не создаёт события, которых нет в соответствующем действии API.
При повторной настройке счётчики попыток ожидающих событий и сведения о последней ошибке сбрасываются. Доставка возобновляется без ожидания прежней задержки. События, исключённые фильтром, пропускаются.
Не поддерживаются параметры Telegram certificate, ip_address и настройка max_connections. Вебхуки используют один последовательный поток доставки на бота. Для HTTPS нужен сертификат, которому доверяет обычное системное хранилище.
deleteWebhook
Отключает отправку на HTTPS-адрес и удаляет секрет. После этого доступен getUpdates.
| Параметр | Тип | Поведение |
|---|---|---|
drop_pending_updates | bool | false сохраняет очередь, true удаляет ожидающие события |
Успешный результат: {"ok": true, "result": true}. Метод можно вызвать повторно, когда вебхук уже отключён.
getWebhookInfo
GET или POST без дополнительных параметров. Пример:
{
"ok": true,
"result": {
"url": "https://bot.example.com/shlyaps/webhook",
"has_custom_certificate": false,
"pending_update_count": 2,
"max_connections": 1,
"allowed_updates": ["message", "callback_query"],
"last_error_date": 1794700000,
"last_error_message": "HTTP 503"
}
}
| Поле | Значение |
|---|---|
url | Текущий адрес или пустая строка при отключённом вебхуке |
has_custom_certificate | Всегда false |
pending_update_count | Число ожидающих событий бота |
max_connections | Всегда 1 |
allowed_updates | Сохранённый фильтр; пустой массив означает все типы |
last_error_date | Время последней неудачной доставки в секундах Unix; поле есть после ошибки |
last_error_message | HTTP-код или код ошибки транспорта без URL и секретов |
last_success_date | Время последней подтверждённой доставки в секундах Unix |
После успешной доставки сведения о прежней ошибке удаляются. Секретный токен метод не возвращает.
Ошибки
| HTTP | Причина |
|---|---|
| 400 | Неподходящий URL, адрес не разрешается в публичный IPv4, недопустимый секрет, тип события или значение параметра |
| 401 | Токен отсутствует, неверен или отозван |
| 403 | Использован пользовательский токен или действует ограничение аккаунта |
| 405 | setWebhook или deleteWebhook вызван без POST |
| 409 | Ещё выполняется getUpdates или доставка вебхука; повторите настройку после её завершения |
| 503 | Временная ошибка сохранения настройки |
Включённый вебхук блокирует getUpdates с HTTP 409 и описанием Conflict: webhook is active, call deleteWebhook first.
В Python SDK 0.5.0 используются bot.set_webhook(), bot.delete_webhook() и bot.get_webhook_info(). Последний возвращает WebhookInfo. Пример Python. Подключить или отключить вебхук также можно через /mybots → бот → «Вебхук» в BotFather.