API MAX в 2026 году: новый домен, Authorization и изменения Webhook

Главное

Разработчикам чатботов и миниприложений MAX необходимо подготовить интеграции к изменениям API:

до 19 июля 2026 года перенаправить запросы с platformapi.max.ru на platformapi2.max.ru и добавить сертификат Минцифры в список доверенных;

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

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

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

Как подготовиться к переходу

1. Заменить базовый домен API на platformapi2.max.ru во всех окружениях и конфигурациях.

2. Удалить токен из queryпараметров и настроить заголовок Authorization: .

3. Проверить цепочку доверия сертификатов и добавить сертификат Минцифры в список доверенных до 19 июля 2026 года.

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

5. Заменить обращения к GET /chats на POST /subscriptions.

6. Убедиться, что нагрузка на platformapi2.max.ru не превышает 30 rps.

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

Методы и примеры запросов

API MAX использует стандартные HTTPметоды:

GET — получение ресурсов;

POST — создание ресурсов, включая отправку сообщений;

PUT — редактирование ресурсов;

DELETE — удаление ресурсов;

PATCH — частичное изменение ресурсов.

Примеры запросов к новому домену:

```text

GET https://platformapi2.max.ru/messages/{messageId}

POST https://platformapi2.max.ru/messages

PATCH https://platformapi2.max.ru/chats/{chatId}

```

Сервер возвращает JSONобъект с данными либо сообщение об ошибке. В документации перечислены основные HTTPкоды: 200, 400, 401, 404, 405, 429 и 503.

Webhook и Long Polling

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

создать или обновить подписку Webhook — POST /subscriptions;

получить список подписок — GET /subscriptions;

получить обновления через Long Polling — GET /updates.

Webhook и Long Polling нельзя использовать одновременно — необходимо выбрать один способ получения событий.

Для чата или канала chatid можно получить через POST /subscriptions или GET /updates: идентификатор приходит в объекте Update для выбранных событий, например botadded или botstarted. В миниприложении также доступен window.WebApp.initData библиотеки MAX Bridge.

Изменения кнопок чатбота

В сообщениях можно использовать кнопки типов callback, link, requestcontact, requestgeolocation, openapp, message и clipboard.

Inlineклавиатура передаётся в объекте attachments с типом inlinekeyboard, а кнопки — в массиве payload.buttons. Сообщение отправляется методом POST /messages.

Ограничения клавиатуры:

до 210 кнопок;

до 30 рядов;

до 7 кнопок в ряду;

до 3 кнопок в ряду для типов link, openapp, requestgeolocation и requestcontact;

максимальная длина ссылки для link — 2048 символов.

Тип callback создаёт событие messagecallback. Кнопка clipboard копирует текст из свойства payload в буфер обмена.

Проверка контакта через requestcontact

Кнопка requestcontact отправляет боту контакт и номер телефона, привязанный к аккаунту пользователя в MAX. Такое сообщение содержит поле hash.

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

Если пользователь отправит контакт другим способом — например, через интерфейс MAX или из телефонной книги, — поле hash отсутствует, поэтому подтвердить принадлежность номера пользователю не получится.

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

Форматирование сообщений

API поддерживает Markdown и HTML. Для Markdown свойству format в NewMessageBody задаётся значение markdown, для HTML — значение html.

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

Медиафайлы и вложения

Сообщения с вложениями отправляются через POST /messages, а медиафайлы image, video, audio, file и share предварительно загружаются методом POST /uploads. В ответ возвращается token: одному токену должен соответствовать один медиафайл.

Для image вместо token можно передать url с прямой ссылкой на изображение. Для остальных типов медиа этот вариант недоступен.

Основные ограничения:

image — до 50 МБ и не более 7680 × 7680 px;

video — до 250 МБ;

audio — до 256 МБ и не более 60 минут;

file — до 4 ГБ;

общее число вложений с видео и изображениями — не более 12;

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

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

Источник

Официальная документация: API MAX.

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

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