MAX API: новый домен, Authorization и требования к Webhook

Что изменилось в MAX API

Разработчикам чатботов и миниприложений MAX необходимо перевести APIзапросы на домен platformapi2.max.ru, изменить способ передачи токена и подготовить вебхуки к новым требованиям безопасности.

Ключевые изменения:

вместо platformapi.max.ru нужно использовать platformapi2.max.ru;

передача токена через queryпараметры больше не поддерживается — токен должен находиться в заголовке Authorization: ;

с 25 мая 2026 года вебхуки должны работать через HTTPS с сертификатом доверенного центра сертификации;

начиная с июня 2026 года метод GET /chats больше не поддерживается;

устаревший тип вложения type=photo необходимо заменить на type=image.

Переход на новый домен API

Все HTTPSзапросы чатботов и миниприложений следует направлять на platformapi2.max.ru. Например:

GET https://platformapi2.max.ru/messages/{messageId} — получение сообщений;

POST https://platformapi2.max.ru/messages — отправка сообщений;

PATCH https://platformapi2.max.ru/chats/{chatId} — изменение информации о чате.

Для стабильной работы ботов документация указывает максимальную частоту запросов к platformapi2.max.ru — 30 rps.

Новый способ передачи токена

Токен больше нельзя передавать через queryпараметры. Для аутентификации необходимо использовать HTTPзаголовок:

```text

Authorization:

```

Разработчикам стоит проверить APIклиенты, библиотеки, прокси и серверные журналы, чтобы старый способ передачи токена не использовался ни в одном окружении.

Требования к Webhook с 25 мая 2026 года

С 25 мая 2026 года MAX прекращает поддержку:

получения вебхуков по HTTP;

самоподписных сертификатов.

Webhook должен использовать HTTPS и сертификат, выданный доверенным центром сертификации, в том числе сертификат Минцифры. В документации также указано, что сертификат Минцифры необходимо добавить в список доверенных.

Для создания или обновления подписки на события используется POST /subscriptions, а для получения списка действующих подписок — GET /subscriptions.

В productionокружении MAX рекомендует использовать только Webhook. Long Polling через GET /updates ограничен по скорости и сроку хранения событий и предназначен для разработки и тестирования. Одновременно использовать Webhook и Long Polling нельзя.

Чем заменить GET /chats

Начиная с июня 2026 года метод GET /chats больше не поддерживается. Для получения списка всех групповых чатов и каналов, в которые добавлен бот, следует использовать POST /subscriptions.

Получить chatid чата или канала можно через подписку:

POST /subscriptions;

GET /updates.

Значение chatid приходит в объекте Update для выбранных событий, например botadded или botstarted. В миниприложении его также можно получить на клиенте через window.WebApp.initData библиотеки MAX Bridge.

Другие важные уточнения документации

Вложения

Для отправки сообщений используется POST /messages, а вложения передаются в объекте attachments. Медиафайлы типов image, video, audio, file и share необходимо предварительно загрузить через POST /uploads. Полученный token затем передаётся во вложении; одному токену должен соответствовать один медиафайл.

Параметр type=photo больше не поддерживается. Вместо него требуется type=image. Для изображений вместо token также можно передать url с прямой ссылкой, но для других типов медиа этот способ недоступен.

Кнопки чатбота

Inlineклавиатура передаётся в attachments с типом inlinekeyboard и массивом payload.buttons. Документация перечисляет кнопки типов callback, link, requestcontact, requestgeolocation, openapp, message и clipboard.

Кнопка clipboard копирует текст из свойства payload в буфер обмена. Кнопка requestcontact позволяет пользователю отправить номер телефона, привязанный к аккаунту MAX. Подлинность такого контакта можно проверить, сопоставив поле hash со значением HMACSHA256(accesstoken, vcfinfo). Перед хешированием символы \r\n в vcfinfo необходимо преобразовать в реальные переносы строк.

Данные, полученные через requestcontact, разрешено использовать только для взаимодействия с текущим чатботом.

Что проверить разработчикам

1. Заменить platformapi.max.ru на platformapi2.max.ru во всех окружениях.

2. Перенести токен из queryпараметров в Authorization: .

3. Перевести Webhook на HTTPS и установить сертификат доверенного центра до 25 мая 2026 года.

4. Заменить GET /chats на предусмотренный документацией сценарий с POST /subscriptions до июня 2026 года.

5. Заменить type=photo на type=image.

6. Проверить ограничение в 30 rps для запросов к platformapi2.max.ru.

7. Не использовать Long Polling в productionокружении и не подключать его одновременно с Webhook.

Источник: документация MAX API.

Полезно: изменение помогает вовремя заметить новую возможность, правило или поведение сервиса.

Риск: если изменение влияет на API, интерфейс или правила платформы, сервисам может понадобиться проверка совместимости.