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

Коротко

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

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

Главные изменения для разработчиков

1. До 19 июля 2026 нужно перенаправить HTTPзапросы с platformapi.max.ru на platformapi2.max.ru.

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

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

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

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

Что проверить в интеграции

1. Домен API

Новые запросы должны идти на домен:

```text

```

Примеры методов из документации:

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

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

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

HTTPметоды сохраняют стандартную семантику:

GET — получить ресурсы;

POST — создать ресурсы, например отправить новые сообщения;

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

DELETE — удалить ресурсы;

PATCH — исправить ресурсы.

2. Авторизация

Если токен передавался в URL через queryпараметры, такой вариант нужно заменить. В документации указано использовать заголовок:

Authorization:

3. Получение списка чатов и каналов

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

POST /subscriptions

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

POST /subscriptions — настроить получение обновлений через Webhook;

GET /subscriptions — получить список всех подписок на обновления через Webhook.

4. Webhook вместо Long Polling для production

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

Поддерживаются два варианта получения уведомлений:

для production — только Webhook;

для разработки и тестирования — Webhook или Long Polling.

Одновременно использовать оба типа нельзя — нужно выбрать один.

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

Как получать chatid

Способ зависит от типа объекта:

| Объект | Как получить chatid |

|||

| Чат | Через подписку: POST /subscriptions или GET /updates. chatid придёт в объекте Update на события, например botadded или botstarted. |

| Канал | Через подписку или синхронно через GET /chats/{link}. |

| Миниприложение | Через подписку или на клиенте через window.WebApp.initData библиотеки MAX Bridge. |

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

В MAX можно подключить inlinekeyboard под сообщением бота. Документация указывает лимит до 210 кнопок, сгруппированных в 30 рядов — до 7 кнопок в каждом. Для кнопок типа link, openapp, requestgeolocation или requestcontact — до 3 кнопок в ряду.

Для кнопки типа link максимальный размер ссылки — 2048 символов.

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

callback — MAX отправляет событие messagecallback, если бот подписан на обновления через Webhook или Long Polling;

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

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

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

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

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

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

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

Пример кнопки clipboard:

```json

{

"type": "clipboard",

"text": "Скопировать",

"payload": "123456"

}

requestcontact и проверка номера через hash

Кнопка requestcontact позволяет пользователю отправить в чатбот контакт и номер телефона, привязанный к аккаунту в МАКС.

Сообщение с контактом содержит поле hash. Оно нужно, чтобы проверить, что пользователь поделился номером телефона, совпадающим с его номером в МАКС. Для проверки сравниваются:

значение поля hash из attachments.payload;

значение функции HMACSHA256(accesstoken, vcfinfo).

Где:

accesstoken — токен чатбота;

vcfinfo — информация о контакте в формате vCard.

Перед хешированием документация требует преобразовать символы \r\n поля vcfinfo в реальные переносы строк.

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

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

Для сообщений чатбота можно использовать базовое форматирование через Markdown или HTML.

Чтобы включить Markdown, установите свойство format в NewMessageBody на значение markdown. Поддерживаются, в частности:

emphasized или emphasized;

strong или strong;

~~strikethrough~~;

++underline++;

` code `;

Inline URL;

^^выделенный^^;

заголовок;

Цитата.

Чтобы включить HTML, установите format в NewMessageBody на значение html. В документации перечислены теги: , , , , , , , , , , Docs , , и заголовки , , , .

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

Медиафайлы и POST /uploads

Для отправки сообщений в чаты и каналы используется POST /messages. Вложения передаются в объекте attachments.

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

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.

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

Для медиафайлов image, video, audio, file, share перед отправкой требуется загрузка через:

POST /uploads

После загрузки возвращается token, который используется для отправки вложения в сообщении. Одному токену должен соответствовать один медиафайл. Для изображений вместо токена можно использовать url — прямую ссылку на изображение в интернете; для других медиафайлов такой способ недоступен.

Что сделать сейчас

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

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

Убрать зависимость от GET /chats и перейти на POST /subscriptions для списка групповых чатов и каналов.

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

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

Если используется type=photo, заменить его на type=image.

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

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