MAX обновил API: новый домен, Webhook и изменения методов

MAX обновил API для разработчиков: новые домены, Webhook и изменения методов

MAX обновил документацию для разработчиков чатботов и миниприложений. Главное изменение: запросы теперь нужно направлять на platformapi2.max.ru вместо platformapi.max.ru, а токен передавать в заголовке Authorization: , а не через queryпараметры.

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

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

Использовать домен platformapi2.max.ru.

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

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

Для productionокружения использовать Webhook, а не Long Polling.

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

Изменения методов API MAX

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

Работа метода POST /chats/{chatId}/members будет ограничена с 9 сентября 2026 года, а с 30 сентября 2026 года метод удалят. После этой даты в API MAX не будет готовой возможности добавлять участников в групповой чат.

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

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

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

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

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

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

Примеры запросов:

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

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

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

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

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

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

Для настройки подписки применяется POST /subscriptions, а для получения списка подписок — GET /subscriptions. Обновления через Long Polling поступают по запросу GET /updates.

chatid для чата или канала можно получить через POST /subscriptions или GET /updates. Для миниприложения также доступен window.WebApp.initData библиотеки MAX Bridge.

Команды и клавиатуры чатботов

Команды для чатбота добавляются методом PATCH /me/commands. Для сценариев обработки команд можно использовать библиотеки JavaScript и Golang.

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

Доступны следующие типы кнопок:

callback — отправляет событие messagecallback;

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

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

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

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

message — отправляет заранее заданный текст;

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

Кнопки передаются в attachments сообщения, отправленного методом POST /messages:

```json

{

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

"attachments": [

"type": "inlinekeyboard",

"payload": {

"buttons": [[

"type": "link",

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

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

}

]]

]

```

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

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

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

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

Форматирование сообщений и медиафайлы

Для форматирования сообщений можно использовать Markdown или HTML. В параметре format указываются значения markdown или html. В комментариях гиперссылки и упоминания пользователей не поддерживаются.

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

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

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

video — до 250 МБ;

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

file — до 4 ГБ.

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

Видео и изображения можно комбинировать с одним вложениемклавиатурой, но общее число вложений не должно превышать 12. Файл можно отправлять только вместе с вложениемклавиатурой — одновременно с изображением или видео он не поддерживается.

Модерация комментариев в каналах

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

POST /messages/{messageId}/comments — опубликовать комментарий;

PUT /messages/{messageId}/comments — отредактировать свои комментарии или комментарии от имени канала при наличии права edit;

GET /messages/{messageId}/comments — получить все комментарии;

GET /messages/{messageId}/comments/{commentId} — получить комментарий по ID;

DELETE /messages/{messageId}/comments — удалить комментарии.

Чтобы бот мог модерировать новые комментарии, нужно включить комментарии в канале, добавить бота как участника и назначить его администратором. Права можно выдать через POST /chats/{chatId}/members/admins, передав в permissions значения readallmessage, edit, write и delete.

Затем настройте подписку через POST /subscriptions на события:

commentcreated — новый комментарий;

commentremoved — комментарий удалён;

commentedited — комментарий изменён.

События поступают на Webhookendpoint в HTTPS POSTзапросах с объектом Update. Идентификатор комментария находится в message.recipient.postid, а его текст — в body.text.

Если комментарий нарушает правила канала, его можно удалить через DELETE /messages/{messageId}/comments. После удаления восстановить комментарий нельзя. Уведомление о причине удаления можно опубликовать через POST /messages/{messageId}/comments.

Подробнее о требованиях и примерах запросов — в документации MAX API.

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

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