API MAX и спецификация OpenApi

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

На этой странице приведено краткое описание API MAX — подробнее читайте в документации

Перед началом работы

Создание бота и взаимодействие с API MAX доступно пока только для юрлиц, ИП и самозанятых, которые являются резидентами РФ

Чтобы создать бота и получить его токен:

Подключитесь к платформе MAX для партнёров, создайте там профиль организации, ИП или самозанятого и дождитесь его верификации
Создайте бота и дождитесь окончания модерации

После успешной модерации будет сформирован токен — уникальный идентификатор бота, который необходим для авторизации HTTPS-запросов к серверу MAX в качестве access_token. Подробнее об управлении ботом и где посмотреть его токен на платформе — в документации

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

В репозитории размещена спецификация OpenAPI для работы с API MAX в формате .YAML

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

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

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

Также вы можете воспользоваться Golang-фреймворком в репозитории на GitHub, чтобы с его помощью настраивать бота, обрабатывать сообщения, команды, callback-запросы и события

Генераторы клиентов

Рекомендуемые генераторы клиентов для разных языков программирования представлены в таблице ниже. Мы проверили их работу: сгенерировали клиент из схемы .YAML, собрали и проверили работу всех методов API MAX на продакшен-сервере, а также описали рекомендации по работе с каждым из них

Вы можете использовать и любые другие удобные генераторы — обратите внимание на общие особенности их использования

Язык	Генератор	На что обратить внимание
TypeScript	`openapi-generator typescript-fetch` 7.25.0	- Генератор не создаёт файлы конфигурации `package.json` и `tsconfig.json`: добавьте их вручную перед сборкой проекта - При создании `Configuration` обязательно передайте `basePath`: по умолчанию клиент обращается к `http://localhost` - При передаче токена используйте поле `apiKey` без префикса `Bearer`
Java	`openapi-generator java --library native` 7.25.0	- По умолчанию генератор Java использует библиотеки на основе Gson (`okhttp-gson`, `retrofit2`), которые некорректно сериализуют дискриминаторы, используя имена классов вместо значений вроде `message_created`, что приводит к неверному формату сообщений. Чтобы этого избежать, при генерации используйте флаг `--library native` — он подключает другие библиотеки, которые более корректно обрабатывают наследование и полиморфные типы - Адрес сервера задайте методом `updateBaseUri()` строго до создания объектов API-классов. После вызова конструктора изменение адреса уже не применится
C#	NSwag `openapi2csclient` 14.7.1	- В результате генерации NSwag создаёт только файл `.cs` — для сборки потребуется минимальный проект под .NET 8.0 - Так как сервер MAX ожидает в URL множественные параметры в виде `?ids=1,2`, а сериализатор NSwag по умолчанию генерирует `?ids=1&ids=2`, списки в query-параметрах передавайте исключительно как `string[]`. Такой массив NSwag сериализует в URL корректно. Использование других типов (например, `List<string>`) приведёт к ошибке в запросе
Python	`openapi-python-client` 0.29.1	- Требуется установить Python версии 3.10 или выше. Если использовать более ранние версии, сборка завершится ошибкой - Библиотека Python по умолчанию добавляет ко всем токенам авторизации `Bearer`. При этом сервер MAX принимает токен в заголовке авторизации в виде чистой строки. Чтобы запрос был корректным, в `AuthenticatedClient` укажите аргумент prefix="" - Распределите webhook-уведомления в конкретный подтип по полю `update_type` самостоятельно. Автоматическая диспетчеризация объекта `Update` не поддерживается - Некоторые подтипы кнопок и разметки генератор включает в базовые классы, поэтому их специфичные поля доступны только через словарь

Общие особенности генераторов клиента

Отсутствие на клиенте валидации ограничений, представленных в схеме
Ограничения из схемы maxLength (например, лимит текста в 4000 символов), pattern и прочие не попадают в генерируемый код. Их проверяет только серверная сторона. Клиент может отправить некорректное значение (например, строку длиной 4001 символ при лимите в 4000), что приведёт к ошибке уже после отправки запроса
Несохранение порядка ключей JSON
Сериализация меняет порядок полей в JSON. При сравнении «отправил — получил» сверяйте значения полей и дискриминаторы, а не исходные строки
Полиморфизм
Перед запуском на продакшен-сервере проведите тест round-trip: разберите webhook-события в ожидаемый подтип и убедитесь, что данные вернулись корректно

Ядро API MAX построено на полиморфных типах. Схема описывает их через discriminator + allOf. Генераторы поддерживают этот паттерн по-разному: одни собирают полноценную диспетчеризацию по значению дискриминатора, другие генерируют базовый тип и игнорируют данные подтипа или пишут в JSON имена классов вместо значений вроде message_created

Как проверить ваш генератор

Проведите round-trip тест для webhook-событий:

Возьмите реальный JSON события
Разберите его с помощью сгенерированного клиента
Сериализуйте объект обратно в JSON

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

API MAX

Авторизация

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

Токен для вызова HTTP-запросов присваивается боту после создания и модерации. Его можно найти на платформе в разделе Чат-боты → Перейти → Расширенные настройки → Настроить

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

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

Базовый URL

https://platform-api2.max.ru/

Методы

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

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

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

Запрос

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

В зависимости от конкретного метода, параметры запроса будут отображаться в 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} — изменить информацию о чате
GET https://platform-api2.max.ru/messages/{messageId}/comments?after={after}&before={before} – получить информацию о всех комментариях к посту за промежуток времени

Ответ

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

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

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

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

Пример ответа при успешном запросе:

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

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

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

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

Name		Name	Last commit message	Last commit date
README.mdx		README.mdx
schema.yaml		schema.yaml

Navigation Menu

Repository files navigation

API MAX и спецификация OpenApi

Перед началом работы

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

Генераторы клиентов

Общие особенности генераторов клиента

API MAX

Авторизация

Базовый URL

Методы

Запрос

Ответ

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

Рекомендации по работе с API

About

Releases

Packages

Contributors

Latest commit

History

Folders and files

Repository files navigation

API MAX и спецификация OpenApi

Перед началом работы

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

Генераторы клиентов

Общие особенности генераторов клиента

API MAX

Авторизация

Базовый URL

Методы

Запрос

Ответ

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

Рекомендации по работе с API

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors