API MAX: переход на platform-api2.max.ru, авторизация и изменения для ботов

Коротко

Документация API MAX обновлена важными требованиями для разработчиков чатботов и миниприложений. Главное: до 19 июля 2026 нужно перенаправить HTTPзапросы с platformapi.max.ru на platformapi2.max.ru, добавить сертификат Минцифры в список доверенных и перестать передавать токен через queryпараметры — вместо этого используйте заголовок Authorization: .

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

Что нужно изменить в интеграциях

1. Перейти на новый домен API

Для корректной работы чатботов и миниприложений MAX документация требует до 19 июля 2026 перенаправить HTTPзапросы:

с platformapi.max.ru;

на platformapi2.max.ru.

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

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

```text

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

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

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

```

2. Передавать токен через заголовок

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

Authorization:

Это изменение важно проверить во всех клиентах, SDKобёртках, cronзадачах и внутренних сервисах, которые обращаются к API MAX.

3. Заменить устаревший GET /chats

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

Для получения списка всех групповых чатов и каналов, в которые добавлен бот, нужно использовать:

POST /subscriptions

Безопасность Webhook и Long Polling

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

Для обновления подписки на события используется:

Документация также уточняет режимы получения обновлений:

для productionокружения — только Webhook;

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

одновременно использовать Webhook и Long Polling нельзя.

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

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

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

Способ получения chatid зависит от типа объекта:

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

|||

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

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

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

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

В MAX можно подключить inlinekeyboard для чатбота. Документация описывает такие ограничения:

до 210 кнопок под сообщением;

до 30 рядов;

до 7 кнопок в каждом ряду;

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

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

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

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

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

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

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

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

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

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

Чтобы добавить кнопки, нужно отправить сообщение методом:

POST /messages

В теле запроса передаётся объект attachments с типом inlinekeyboard и массивом кнопок payload.buttons. Для каждой кнопки обязателен параметр text.

Пример кнопки link из документации:

```json

{

"text": "Это сообщение с кнопкойссылкой",

"attachments": [

"type": "inlinekeyboard",

"payload": {

"buttons": [

[

"type": "link",

"text": "Откройте сайт",

"url": "https://example.com"

}

]

requestcontact: проверка номера пользователя

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

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

Для проверки сравниваются:

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

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

Где:

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

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

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

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

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

API MAX поддерживает базовое форматирование текста сообщений через Markdown или HTML.

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

markdown

Чтобы включить HTMLразбор:

html

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

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

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

Вложения передаются в объекте attachments. Возможные типы type:

image — изображения;

video — видеофайлы;

audio — аудиофайлы;

file — другие медиафайлы;

sticker — стикеры;

inlinekeyboard — кнопки клавиатуры;

location — геолокация;

share — медиафайлы с превью.

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

Ограничения по медиа

Из документации:

image: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC; до 50 МБ и не более 7680 x 7680 px — должны выполняться оба критерия;

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

audio: MP3, WAV, M4A и другие; до 256 МБ и не более 60 минут — должны выполняться оба критерия;

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

Перед отправкой медиафайлов image, video, audio, file, share их нужно предварительно загрузить через:

POST /uploads

В результате загрузки возвращается token, который используется для отправки вложения в сообщении. Одному токену должен соответствовать один медиафайл.

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

Чеклист для разработчиков MAX

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

[ ] Добавить сертификат Минцифры в доверенные.

[ ] Убрать передачу токена через queryпараметры.

[ ] Использовать Authorization: .

[ ] Заменить GET /chats на POST /subscriptions, если нужен список групповых чатов и каналов с ботом.

[ ] Проверить Webhook: HTTPS и сертификат доверенного центра.

[ ] Не использовать Long Polling для production.

[ ] Учитывать лимит 30 rps для platformapi2.max.ru.

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

[ ] Загружать медиа через POST /uploads, если это требуется для типа вложения.

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

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