Обзор

Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на домен platform-api2.max.ru вместо platform-api.max.ru. Также убедитесь, что добавили сертификат Минцифры в список доверенных

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

API (Application Programming Interface) — это посредник между разработчиком приложений и средой, с которой это приложение должно взаимодействовать. API упрощает написание кода за счёт набора готовых классов, функций или структур для работы с данными

API MAX — это интерфейс, который позволяет ботам взаимодействовать с платформой и получать необходимые данные с помощью HTTPS-запросов к серверу. В этом разделе расскажем, как подготовиться к использованию API MAX

Авторизация

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

Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на платформе в разделе Чат-боты → ⋮ → Настройки

Eсли вы верифицировали профиль и создали бота в мини-приложении «MAX для бизнеса», получить токен можно там же или в боте «MAX для бизнеса» с помощью команды Получить токен

Рекомендуем не разглашать токен посторонним, чтобы они не получили доступ к управлению ботом. Токен может быть отозван за нарушение Правил платформы

Методы

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

С 9 сентября 2026 работа метода POST /chats/{chatId}/members будет ограничена, а с 30 сентября 2026 он будет удалён

С 30 сентября API MAX не предоставляет готовой возможности для добавления участников в групповой чат. Однако мы постоянно работаем над расширением функциональности API — следите за обновлениями документации

HTTPS-запросы на домен platform-api2.max.ru вызывают методы — условные команды, которые соответствуют той или иной операции с базой данных. Например, получение, запись или удаление какой-либо информации

Параметры запроса должны содержать HTTP-метод, соответствующий необходимой операции:

GET — получить ресурсы
POST — создать ресурсы (например, отправить новые сообщения)
PUT — редактировать ресурсы
DELETE — удалить ресурсы
PATCH — исправить ресурсы

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

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

GET https://platform-api2.max.ru/messages/{messageId} — получить сообщения
POST https://platform-api2.max.ru/messages — отправить сообщения
PATCH https://platform-api2.max.ru/chats/{chatId} — изменить информацию о чате

В ответ сервер вернёт 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
}

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

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

200 — успешный запрос
400 — недействительный запрос
401 — ошибка аутентификации
404 — ресурс не найден
405 — метод не допускается
429 — превышено количество запросов
503 — сервис недоступен

Спецификация OpenAPI

Для работы с API MAX вы можете скачать спецификацию OpenAPI в формате .YAML в репозитории на GitHub

Используйте спецификацию и подходящий вам генератора кода, чтобы получить готовый интерфейс (модели данных и функции для вызова эндпоинтов API) на языке разработки вашего приложения, например: Python, C#, PHP, Java, Swift или Kotlin. Это упростит проверку типов передаваемых данных, сократит время на ручной перенос моделей, парсинг и сериализацию JSON-данных и позволит сосредоточиться на бизнес-логике вашего приложения

Обратите внимание, спецификация содержит краткое описание параметров и эндпоинтов. Подробнее читайте в текущем разделе и описании конкретных методов

Если вы пишете ботов на TypeScript, JavaScript или Golang, рекомендуем также использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделах «Библиотека JavaScript» и «Библиотека Golang» или на GitHub: JavaScript, Golang

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