API MAX в 2026 году: сроки и изменения для разработчиков

Главное

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

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

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

учесть прекращение поддержки GET /chats начиная с июня 2026 года;

до 25 мая 2026 года перевести Webhook на HTTPS и отказаться от самоподписных сертификатов;

заменить устаревший type=photo на type=image.

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

Переезд на platformapi2.max.ru

Для корректной работы интеграций необходимо до 19 июля 2026 года заменить домен API:

старый домен — platformapi.max.ru;

новый домен — platformapi2.max.ru.

Одновременно документация требует добавить сертификат Минцифры в список доверенных. После миграции запросы к 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} — изменение информации о чате.

Для стабильной работы бота необходимо соблюдать ограничение — не более 30 rps к platformapi2.max.ru.

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

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

```text

Authorization:

```

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

GET /chats прекращает работу

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

POST /subscriptions

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

POST /subscriptions — создание или обновление подписки;

GET /updates — получение событий через Long Polling.

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

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

С 25 мая 2026 года MAX прекращает поддержку получения вебхуков по HTTP и использование самоподписных сертификатов. Необходимо перейти на HTTPS и сертификат доверенного центра сертификации, в том числе можно использовать сертификат Минцифры.

Для настройки уведомлений используются методы:

POST /subscriptions — указать URL, на который будут приходить события;

GET /subscriptions — получить список действующих подписок.

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

Изменения в отправке медиафайлов

Сообщения отправляются методом POST /messages, а вложения передаются в объекте attachments. Параметр type=photo больше не поддерживается — вместо него нужно указывать type=image.

Поддерживаемые типы вложений включают:

image — JPG, JPEG, PNG, GIF, TIFF, BMP и HEIC, до 50 МБ и не более 7680 × 7680 px;

video — MP4, MOV, MKV и WEBM, до 250 МБ;

audio — MP3, WAV, M4A и другие форматы, до 256 МБ и не более 60 минут;

file — TXT, DOC, PDF и другие распространённые форматы, до 4 ГБ;

sticker;

inlinekeyboard;

location;

share.

Перед отправкой image, video, audio, file или share файл необходимо загрузить через POST /uploads. В ответ API возвращает token: одному токену должен соответствовать один медиафайл. Для image вместо токена разрешена прямая ссылка url; для остальных типов такой вариант недоступен.

В одном сообщении допускается не более 12 вложений с видео и изображениями. К ним можно добавить одно вложение с кнопками. file нельзя отправлять вместе с изображением или видео: поддерживается комбинация из одного файла и одного вложения с кнопками.

Inlineклавиатура и кнопки

Чтобы прикрепить клавиатуру, отправьте POST /messages и передайте в attachments объект с типом inlinekeyboard, а кнопки разместите в массиве payload.buttons. Для каждой кнопки обязателен параметр text.

Inlineклавиатура поддерживает до 210 кнопок в 30 рядах. В одном ряду может быть до семи кнопок, а для типов link, openapp, requestgeolocation и requestcontact — до трёх. Максимальная длина ссылки для link составляет 2048 символов.

Доступные типы кнопок:

callback — вызывает событие messagecallback;

link — открывает ссылку в новой вкладке;

requestcontact — запрашивает контакт и номер телефона;

requestgeolocation — запрашивает местоположение;

openapp — открывает миниприложение;

message — отправляет боту текстовое сообщение;

clipboard — копирует значение payload в буфер обмена.

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

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

Для проверки нужно сравнить полученный hash со значением:

HMACSHA256(accesstoken, vcfinfo)

Перед вычислением хеша символы \r\n в поле vcfinfo необходимо преобразовать в реальные переносы строк. Если пользователь отправит контакт другим способом — например, через интерфейс MAX или из телефонной книги, — поля hash в сообщении не будет, поэтому подтвердить принадлежность номера пользователю не получится.

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

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

API MAX поддерживает Markdown и HTML. Чтобы включить обработку разметки, установите свойство format в NewMessageBody:

значение markdown — для Markdown;

значение html — для HTML.

Для упоминания пользователя следует указывать его полное имя из профиля MAX, включая фамилию. Если фамилии нет, используется только имя.

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

1. Заменить platformapi.max.ru на platformapi2.max.ru до 19 июля 2026 года.

2. Добавить сертификат Минцифры в список доверенных.

3. Удалить передачу токена через queryпараметры и использовать Authorization: .

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

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

6. Не использовать Long Polling в productionокружении.

7. Проверить соблюдение лимита 30 rps.

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

9. Проверить ограничения для attachments, загрузку через POST /uploads и использование token.

Полные описания методов и параметров опубликованы в официальной документации API MAX.

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

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