

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

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

> Если вы используете AI-агента для создания бота, установите ему специальный навык [MAX Messenger Agent Skill](https://github.com/max-messenger/max-agents-skill) — он разработает бота по заданным условиям

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

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

## Авторизация

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

Токен для вызова HTTPS-запросов присваивается при создании бота — его можно найти на [платформе](https://business.max.ru/self) в разделе **Чат-боты** → **⋮** → **Настройки** 

Eсли вы верифицировали профиль и создали бота в [мини-приложении «MAX для бизнеса»](https://max.ru/business_bot?startapp), получить токен можно там же или в [боте «MAX для бизнеса»](https://max.ru/business_bot) с помощью команды **Получить токен**

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

## Методы

**С июня 2026** метод `GET /chats` больше не поддерживается. Вместо него для получения списка всех групповых чатов и каналов, в которые добавлен бот, используйте [POST /subscriptions](/docs-api/methods/POST/subscriptions). Подробнее — на [странице «Получение ID чата или канала»](/docs-api/use-cases/getting-chat-id)

**С 9 сентября 2026** ограничена работа метода `POST /chats/{chatId}/members`

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

В каждом запросе укажите HTTPS-метод, который соответствует операции:

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

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

Примеры запросов:
- `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`**:

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

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

| Ответ сервера | Список методов |
| --- | ---|
| - HTTP-код `200`- Поле `"success": false`, код ошибки и сообщение об ошибке
{
    "success": false, 
  	"code": "not.found",
  	"message": "Resource not found"
}
 | - [POST `/subscriptions`](/docs-api/methods/POST/subscriptions/)- [DELETE `/subscriptions`](/docs-api/methods/DELETE/subscriptions/)- [POST `/chats/{chatId}/members`](/docs-api/methods/POST/chats/-chatId-/members/)- [DELETE `/chats/{chatId}/members/me`](/docs-api/methods/DELETE/chats/-chatId-/members/me/)- [DELETE `/chats/{chatId}/pin`](/docs-api/methods/DELETE/chats/-chatId-/pin/)- [DELETE `/chats/{chatId}/members`](/docs-api/methods/DELETE/chats/-chatId-/members/)- [POST `/chats/{chatId}/actions`](/docs-api/methods/POST/chats/-chatId-/actions/)- [PUT `/messages`](/docs-api/methods/PUT/messages/)- [DELETE `/messages`](/docs-api/methods/DELETE/messages/) |
| - 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](https://github.com/max-messenger/api-schema)

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

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

Если вы пишете ботов на TypeScript, JavaScript или Golang, рекомендуем также использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделах [«Библиотека JavaScript»](/docs/chatbots/bots-coding/js) и [«Библиотека Golang»](/docs/chatbots/bots-coding/go) или на GitHub: [JavaScript](https://github.com/max-messenger/max-bot-api-client-ts), [Golang](https://github.com/max-messenger/max-bot-api-client-go)

 Если у вас возникли вопросы, [посмотрите раздел с ответами](/help)