Получение обновлений: webhook

Боту можно задать настройку webhook_url, после чего все обновления будут отправляться в виде POST-запроса по указанному адресу. Тело запроса будет идентично ответу метода bot/v1/messages/getUpdates/.

Задание webhook_url

Метод позволяет задать боту вебхук.

HTTP метод: POST

URL: https://botapi.messenger.yandex.net/bot/v1/self/update/

Заголовки

Authorization: OAuth <токен>
Content-Type: application/json

Тело запроса (JSON или URL Query)

Пример запроса (POST) с установкой webhook_url

curl -H 'Authorization: OAuth AtXXXXXXXXXXX' \
     -H "Content-Type: application/json" \
     -d '{"webhook_url": "https://my-service.ru/bot_webhook"}' \
     'https://botapi.messenger.yandex.net/bot/v1/self/update/'

Пример успешного ответа с установкой

{
  "ok": true,
  "id": "103ecea2-e303-478d-91a7-b6d423ace527",
  "display_name": "My bot",
  "webhook_url": "https://my-service.ru/bot_webhook",
  "organizations": [567890],
  "login": "bot@my-service.ru"
}

Пример запроса (POST) со сбросом webhook_url

curl -H 'Authorization: OAuth AtXXXXXXXXXXX' \
     -H "Content-Type: application/json" \
     -d '{"webhook_url": null}' \
     'https://botapi.messenger.yandex.net/bot/v1/self/update/'

Пример успешного ответа со сбросом

{
  "ok": true,
  "id": "103ecea2-e303-478d-91a7-b6d423ace527",
  "display_name": "My bot",
  "webhook_url": null,
  "organizations": [567890],
  "login": "bot@my-service.ru"
}

Гарантии доставки

1. Доставка сообщений на вебхук работает по принципу "at least once" (сообщение может быть доставлено несколько раз).

2. Гарантируется порядок доставки сообщений в рамках комбинации бот + чат.

3. Если вебхук недоступен (connection timeout = 100ms или read timeout = 1s или http-код ответа 5xx), будут осуществлены повторные попытки через интервал (интервал действует в рамках комбинации бот + чат), вычисляемый как:

   • до 8ой попытки включительно: <время_отправки_сообщения> + <номер_текущей_попытки> * 5 (в секундах).
   • после 8ой попытки: <время_отправки_сообщения> + <номер_текущей_попытки> * 45 (в секундах).

4. Все остальные ответы от вебхука (например статусы 2xx или 4xx) считаются финальными и не предусматривают повторных попыток.

5. Через 24 часа с момента отправки все недоставленные сообщения удаляются и не будут получены ботом.