Обзор

Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на домен 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-метод, который соответствует операции:

В зависимости от конкретного метода, параметры запроса будут отображаться в пути, URL-параметрах или теле запроса

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

В ответ сервер вернёт JSON-объект с запрошенными данными или сообщение об ошибке, если что-то пойдёт не так

JSON — это формат записи данных в виде пар <ИМЯ_СВОЙСТВА>: <ЗНАЧЕНИЕ>

Пример запроса GET /me:

BASH
curl -X GET "https://platform-api2.max.ru/me" \
  -H "Authorization: {access_token}"

Пример ответа на запрос GET /me:

JSON
{
	"user_id": 1,
    "first_name": "My Bot",
	"name": "My Bot",
	"username": "my_bot",
	"is_bot": true,
	"last_activity_time": 1737500130100
}

Результат выполнения запроса

HTTP-коды ответов

Помимо JSON, сервер вернёт трёхзначный HTTP-код, информирующий об успешном выполнении запроса или об ошибке:

HTTP-код 200 означает, что запрос дошёл до сервера и был обработан, но не гарантирует, что сама операция выполнена успешно. Ошибка может вернуться двумя способами:

Чтобы понять, какой формат использует конкретный метод, посмотрите блок «Результат» на странице этого метода или таблицу ниже

Коды 5xx означают, что сервер получил запрос, но не смог его обработать из-за внутренней ошибки или сбоя инфраструктуры. В этом случае тело ответа в описанном ниже формате не возвращается

Чтобы корректно обработать ошибку, проверяйте и HTTP-код, и тело ответа

Тело ответа

В случае успешного выполнения запроса сервер вернёт:

В случае ошибки сервер вернёт ответ в одном из следующих форматов:

Ответ сервераСписок методов
  • HTTP-код 200
  • Поле "success": false, код ошибки и сообщение об ошибке
    {
        "success": false, 
      	"code": "not.found",
      	"message": "Resource not found"
    }
  • HTTP-код 4xx
  • Код и сообщение об ошибке
    {
        "code": "not.found",
    	"message": "Resource not found"
    }
Остальные методы

Разработчикам ботов, которые определяют ошибку по полю 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

ℹ️ Если у вас возникли вопросы, посмотрите раздел с ответами