Обзор
Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на доменplatform-api2.max.ruвместоplatform-api.max.ru. Также убедитесь, что добавили сертификат Минцифры в список доверенных
Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <access_token>
Если вы используете AI-агента для создания бота, установите ему специальный навык MAX Messenger Agent Skill — он разработает бота по заданным условиям
API (Application Programming Interface) — это посредник между разработчиком приложений и средой, с которой это приложение должно взаимодействовать. API упрощает написание кода за счёт набора готовых классов, функций или структур для работы с данными
API MAX — это интерфейс, который позволяет ботам взаимодействовать с платформой и получать необходимые данные с помощью HTTPS-запросов к серверу. В этом разделе расскажем, как подготовиться к использованию API приложения
Авторизация
Передача токена через query-параметры больше не поддерживается — используйте заголовок
Authorization: <access_token>
Токен для вызова HTTPS-запросов присваивается при создании бота — его можно найти на платформе в разделе Чат-боты → ⋮ → Настройки
Eсли вы верифицировали профиль и создали бота в мини-приложении «MAX для бизнеса», получить токен можно там же или в боте «MAX для бизнеса» с помощью команды Получить токен
Рекомендуем не разглашать токен посторонним, чтобы они не получили доступ к управлению ботом. Токен может быть отозван за нарушение Правил платформы
Методы
С июня 2026 метод GET /chats больше не поддерживается. Вместо него для получения списка всех групповых чатов и каналов, в которые добавлен бот, используйте POST /subscriptions. Подробнее — на странице «Получение ID чата или канала»
С 9 сентября 2026 ограничена работа метода POST /chats/{chatId}/members
HTTPS-запросы на домен platform-api2.max.ru вызывают методы — условные команды, которые соответствуют той или иной операции с базой данных. Например, получение, запись или удаление какой-либо информации
В каждом запросе укажите HTTPS-метод, который соответствует операции:
GET— получить ресурсыPOST— создать ресурсы (например, отправить новые сообщения)PUT— редактировать ресурсыDELETE— удалить ресурсыPATCH— внести изменения в ресурсы
В зависимости от конкретного метода, параметры запроса будут отображаться в пути, URL-параметрах или теле запроса
Примеры запросов:
GEThttps://platform-api2.max.ru/messages/{messageId}— получить сообщениеPOSThttps://platform-api2.max.ru/messages— отправить сообщениеPATCHhttps://platform-api2.max.ru/chats/{chatId}— изменить информацию о чате
В ответ сервер вернёт JSON-объект с запрошенными данными или сообщение об ошибке, если что-то пойдёт не так
JSON — это формат записи данных в виде пар <ИМЯ_СВОЙСТВА>: <ЗНАЧЕНИЕ>
Пример запроса GET /me:
curl -X GET "https://platform-api2.max.ru/me" \
-H "Authorization: {access_token}"Пример ответа на запрос GET /me:
{
"user_id": 1,
"first_name": "My Bot",
"name": "My Bot",
"username": "my_bot",
"is_bot": true,
"last_activity_time": 1737500130100
}Результат выполнения запроса
HTTP-коды ответов
Помимо JSON, сервер вернёт трёхзначный HTTP-код, информирующий об успешном выполнении запроса или об ошибке:
200— успешный запрос400— некорректный запрос401— ошибка аутентификации404— запрашиваемый ресурс не найден405— метод не поддерживается429— превышено количество запросов503— сервис недоступен
HTTP-код 200 означает, что запрос дошёл до сервера и был обработан, но не гарантирует, что сама операция выполнена успешно. Ошибка может вернуться двумя способами:
- Как HTTP-код
200с ошибкой в теле ответа — для части методов сервер возвращает код200, а признак ошибки передаёт в теле ответа ("success": falseи код ошибки) - Как HTTP-код
4xx— для части методов ошибки возвращаются вместе с соответствующим HTTP-статусом
Чтобы понять, какой формат использует конкретный метод, посмотрите блок «Результат» на странице этого метода или таблицу ниже
Коды 5xx означают, что сервер получил запрос, но не смог его обработать из-за внутренней ошибки или сбоя инфраструктуры. В этом случае тело ответа в описанном ниже формате не возвращается
Чтобы корректно обработать ошибку, проверяйте и HTTP-код, и тело ответа
Тело ответа
В случае успешного выполнения запроса сервер вернёт:
- HTTP-код
200 - Для некоторых методов — параметр
"success": true - Запрошенные данные в формате JSON
В случае ошибки сервер вернёт ответ в одном из следующих форматов:
| Ответ сервера | Список методов |
|---|---|
| |
| Остальные методы |
Разработчикам ботов, которые определяют ошибку по полю message, нужно перейти на поле code для унификации обработки ошибок. Поле code содержит код ошибки в формате some.error, например not.found, chat.denied, proto.payload
Спецификация OpenAPI
Для работы с API MAX вы можете скачать спецификацию OpenAPI в формате YAML в репозитории на GitHub
Используйте спецификацию и подходящий вам генератора кода, чтобы получить готовый интерфейс (модели данных и функции для вызова эндпоинтов API) на языке разработки вашего приложения, например: Python, C#, PHP, Java, Swift или Kotlin. Это упростит проверку типов передаваемых данных, сократит время на ручной перенос моделей, парсинг и сериализацию JSON-данных и позволит сосредоточиться на бизнес-логике вашего приложения
Обратите внимание, спецификация содержит краткое описание параметров и эндпоинтов. Подробнее читайте в текущем разделе и описании конкретных методов
Если вы пишете ботов на TypeScript, JavaScript или Golang, рекомендуем также использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделах «Библиотека JavaScript» и «Библиотека Golang» или на GitHub: JavaScript, Golang
Если у вас возникли вопросы, посмотрите раздел с ответами