---
slug: "max-bot-api"
name: "MAX Bot API"
vendor: "MAX (VK)"
industry: "communications"
docsUrl: "https://dev.max.ru/docs-api"
version: 2
updatedAt: "2026-10-24"
---

# MAX Bot API

Отрасль: Связь и уведомления. Актуально на 2026-10-24.

HTTP API для ботов мессенджера MAX: информация о боте, отправка, редактирование, удаление и получение сообщений, ответы на нажатия кнопок, загрузка файлов, управление чатами и участниками. Получать события можно через Webhook-подписку (рекомендуется для production) или long polling (`GET /updates`, для разработки и тестов). Ответы — JSON.

## Сценарии

### Отправить сообщение пользователю или в чат

Уведомления из своего сервиса в мессенджер MAX: заказ оформлен, запись подтверждена, новая заявка.

1. Получи токен бота и передавай его в заголовке Authorization без префикса. Передача токена в параметре access_token больше не работает. Проверь токен: GET /me вернёт данные бота.
2. Отправь сообщение: POST /messages с user_id (личное сообщение) или chat_id (чат или канал) в строке запроса и text в теле — до 4000 символов. Для форматирования передай format = html или markdown.
3. В ответе — объект message с ID сообщения: сохрани его, если сообщение потом нужно будет изменить через PUT /messages или удалить через DELETE /messages.
4. Не отправляй больше 2 сообщений в секунду в один диалог или чат и больше 30 запросов в секунду всего — иначе придёт 429. Ответ 403 значит, что пользователь остановил бота.

```bash
curl -X POST "https://platform-api2.max.ru/messages?user_id=<user_id>" \
  -H "Authorization: $MAX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text": "<b>Заказ №1042 оформлен</b>\nСумма: 15 000 ₽", "format": "html"}'
```

### Принимать сообщения через вебхук

Бот на сервере: MAX присылает каждое событие на твой адрес — рекомендуемый способ для боевого режима.

1. Подпишись: POST /subscriptions с url (только HTTPS на порту 443, порт в адресе не указывается), update_types (например, message_created и bot_started) и secret — строкой от 5 до 256 символов.
2. Сертификат сервера должен быть от доверенного центра или Минцифры, с полной цепочкой. Самоподписанные не принимаются.
3. В каждом запросе MAX передаёт заголовок X-Max-Bot-Api-Secret — сверяй его со своим secret и отбрасывай чужие запросы.
4. Отвечай пользователю отдельным вызовом POST /messages с chat_id или user_id из события.
5. Метод возвращает HTTP 200 и при неудаче — проверяй поле success в ответе.

```bash
curl -X POST https://platform-api2.max.ru/subscriptions \
  -H "Authorization: $MAX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.ru/max/webhook", "update_types": ["message_created", "message_callback", "bot_started"], "secret": "s3cr3t_Random_42"}'
```

### Бот без сервера: long polling для разработки

Получать события в цикле — удобно для отладки и ботов без публичного HTTPS-адреса.

1. В цикле вызывай GET /updates с timeout (до 90 секунд ожидания) и types — нужными типами событий.
2. В ответе updates и marker. В следующий запрос передай этот marker: всё до него считается прочитанным. Без marker вернётся только последнее обновление.
3. На каждое сообщение отвечай через POST /messages.
4. Для событий из групповых чатов и каналов бот должен быть администратором.

```python
import requests

API = "https://platform-api2.max.ru"
H = {"Authorization": "<токен бота>"}
marker = None
while True:
    params = {"timeout": 30, "types": "message_created"}
    if marker:
        params["marker"] = marker
    r = requests.get(f"{API}/updates", headers=H, params=params, timeout=40).json()
    marker = r.get("marker", marker)
    for upd in r.get("updates", []):
        msg = upd.get("message", {})
        chat_id = msg.get("recipient", {}).get("chat_id")
        text = msg.get("body", {}).get("text")
        if chat_id and text:
            requests.post(f"{API}/messages", headers=H, params={"chat_id": chat_id}, json={"text": f"Вы написали: {text}"})
```

### Кнопки под сообщением и ответ на нажатие

Подтвердить или отменить заказ одной кнопкой, без ввода текста.

1. Отправь сообщение с кнопками: POST /messages с attachments, где type = inline_keyboard и payload.buttons — строки кнопок. Кнопка type = callback несёт payload — по нему поймёшь, что нажали; кнопка type = link открывает ссылку.
2. Нажатие приходит событием message_callback (через вебхук или GET /updates) с callback_id и payload.
3. Ответь на нажатие: POST /answers с callback_id в строке запроса. В теле можно передать message — новое содержимое сообщения, например без кнопок и с итогом.
4. Сообщения с inline_keyboard можно редактировать без ограничения срока через PUT /messages с message_id.

```bash
curl -X POST "https://platform-api2.max.ru/messages?user_id=<user_id>" \
  -H "Authorization: $MAX_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "text": "Заказ №1042 на 15 000 ₽. Подтвердить?",
        "attachments": [{"type": "inline_keyboard", "payload": {"buttons": [[
          {"type": "callback", "text": "Подтвердить", "payload": "order:1042:ok"},
          {"type": "callback", "text": "Отменить", "payload": "order:1042:cancel"}
        ]]}}]
      }'

curl -X POST "https://platform-api2.max.ru/answers?callback_id=<callback_id>" \
  -H "Authorization: $MAX_TOKEN" -H 'Content-Type: application/json' \
  -d '{"message": {"text": "Заказ №1042 подтверждён"}}'
```

### Отправить файл или картинку

Прислать счёт, договор или фото товара вложением.

1. Получи адрес загрузки: POST /uploads с type — image, video, audio или file (photo больше не поддерживается). На один url загружается один файл.
2. Загрузи файл на полученный url multipart-формой. Токен вложения приходит в ответе /uploads (для части типов) или в ответе на загрузку.
3. Отправь сообщение: POST /messages с attachments = [{type, payload: {token}}].
4. Сразу после загрузки файл может быть ещё не обработан — придёт ошибка attachment.not.ready. Повторяй отправку с растущим интервалом.
5. Ограничения: картинка — до 50 МБ, видео — до 250 МБ, файл — до 4 ГБ.

```bash
UPLOAD_URL=$(curl -s -X POST "https://platform-api2.max.ru/uploads?type=file" -H "Authorization: $MAX_TOKEN" | jq -r .url)
TOKEN=$(curl -s -F "data=@invoice-1042.pdf" "$UPLOAD_URL" | jq -r .token)

curl -X POST "https://platform-api2.max.ru/messages?user_id=<user_id>" \
  -H "Authorization: $MAX_TOKEN" -H 'Content-Type: application/json' \
  -d "{\"text\": \"Счёт по заказу №1042\", \"attachments\": [{\"type\": \"file\", \"payload\": {\"token\": \"$TOKEN\"}}]}"
```

## Базовые URL

- Боевой: `https://platform-api2.max.ru`
- Документация просит отправлять запросы на  вместо старого .: `platform-api2.max.ru`

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

Тип: API-ключ

Токен бота передаётся в заголовке `Authorization: <access_token>` (без префикса). Передача токена в query-параметре `access_token` больше не поддерживается.

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

## Методы

### GET /me — Информация о боте

Возвращает объект User (BotInfo): `user_id`, `first_name`, `username`, `is_bot`, `last_activity_time`, `description`, `avatar_url`, `commands`.

### POST /messages — Отправка сообщения

Адресат задаётся `user_id` или `chat_id`. В ответе — объект `message` созданного сообщения или поста.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `user_id` | query | integer | нет | ID пользователя-получателя |
| `chat_id` | query | integer | нет | ID чата или канала |
| `disable_link_preview` | query | boolean | нет | Не генерировать превью ссылок |
| `text` | body | string | нет | Текст, до 4000 символов |
| `attachments` | body | array | нет | Вложения: файлы (payload.token из /uploads), inline_keyboard и др. |
| `link` | body | object | нет | Ссылка на сообщение в чате или пост в канале (ответ или пересылка) |
| `notify` | body | boolean | нет | Push-уведомления участникам, по умолчанию true |
| `format` | body | string | нет | Форматирование текста: markdown или html |

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

```
curl -X POST "https://platform-api2.max.ru/messages?user_id={user_id}" \
  -H "Authorization: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Это сообщение с кнопкой-ссылкой",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "link",
              "text": "Откройте сайт",
              "url": "https://example.com"
            }
          ]
        ]
      }
    }
  ]
}'
```

### PUT /messages — Редактирование сообщения

Сообщения с `inline_keyboard` и любые сообщения в групповых чатах и каналах редактируются без ограничения срока; остальные сообщения в диалогах с ботом — если отправлены меньше 7 суток назад. Ответ: `success`, `message`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `message_id` | query | string | да | ID редактируемого сообщения |
| `text` | body | string | нет | Новый текст, до 4000 символов |
| `attachments` | body | array | нет | null или отсутствие — без изменений; пустой массив удаляет все вложения |
| `link` | body | object | нет | Ссылка на сообщение или пост |
| `notify` | body | boolean | нет | Push-уведомления, по умолчанию true |
| `format` | body | string | нет | markdown или html |

### DELETE /messages — Удаление сообщения

Удаляет сообщение или пост.

### GET /messages — Получение сообщений

Нужен `chat_id` или `message_ids`. Сообщения по `chat_id` возвращаются от новых к старым; бот должен быть администратором чата.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `chat_id` | query | integer | нет | ID чата или канала |
| `message_ids` | query | array | нет | ID сообщений через запятую |
| `from` | query | integer | нет | Граница времени, Unix-время в миллисекундах |
| `to` | query | integer | нет | Граница времени, Unix-время в миллисекундах |
| `count` | query | integer | нет | 1–100, по умолчанию 50 |

### POST /answers — Ответ на нажатие кнопки

Ответ: `success`, `message`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `callback_id` | query | string | да | ID нажатой кнопки |
| `disable_link_preview` | query | boolean | нет | Не генерировать превью ссылок |
| `message` | body | object | нет | Новое содержимое текущего сообщения, если его нужно изменить |

### GET /updates — Получение событий (long polling)

Для событий из групповых чатов и каналов бот должен быть администратором.

В ответе: `updates[]` и `marker` — указатель на следующую страницу; всё до него считается прочитанным.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `limit` | query | integer | нет | 1–1000, по умолчанию 100 |
| `timeout` | query | integer | нет | Ожидание в секундах, 0–90, по умолчанию 30 |
| `marker` | query | integer | нет | marker из предыдущего ответа; без него вернётся только последнее обновление |
| `types` | query | array | нет | Типы событий, например message_created,message_callback |

### POST /subscriptions — Подписка на Webhook

Ответ: `success`, `message`.

Также есть `GET /subscriptions` (список подписок) и `DELETE /subscriptions` (отписка).

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `url` | body | string | да | HTTPS-адрес, только порт 443 (порт в URL не указывается) |
| `update_types` | body | array | нет | Типы событий, например ["message_created", "bot_started"] |
| `secret` | body | string | нет | 5–256 символов; приходит в заголовке X-Max-Bot-Api-Secret каждого вебхука |

### POST /uploads — Получение URL для загрузки файла

Возвращает `url` для загрузки и (для части типов) `token` для вложения. По одному `url` загружается один файл.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `type` | query | string | да | image, video, audio или file (photo больше не поддерживается) |

## Нюансы

- Загрузка файла: `POST /uploads?type=...` → загрузить файл на `url` (multipart целиком или resumable частями) → передать токен в `attachments[].payload.token` в `POST /messages` или `PUT /messages`.
- Сразу после загрузки файл может быть не обработан — ошибка `attachment.not.ready`; повторяйте отправку с растущим интервалом.
- Вебхук: только HTTPS на порту 443, сертификат доверенного центра или Минцифры, полная цепочка сертификатов; самоподписанные сертификаты не поддерживаются. Проверяйте заголовок `X-Max-Bot-Api-Secret`.
- `GET /chats` не поддерживается с июня 2026; `POST /chats/{chatId}/members` удалён с 30 сентября 2026.
- Методы `PUT`/`POST /subscriptions`/`POST /answers` возвращают HTTP 200 и при неуспехе — проверяйте поле `success`.

## Ошибки

| Код | Описание |
|---|---|
| `400` | Некорректный запрос |
| `401` | Ошибка авторизации: токен неверен или недействителен |
| `403` | Бот приостановлен пользователем или нет доступа к чату |
| `404` | Ресурс не найден |
| `405` | Метод не разрешён |
| `429` | Превышено количество запросов |
| `503` | Сервис недоступен |

## Ограничения

- Не больше 30 запросов в секунду на `platform-api2.max.ru`.
- Не больше 2 отправленных или отредактированных сообщений в секунду в один диалог, чат или канал.
- Размер файлов: `image` — до 50 МБ и 7680×7680 px; `video` — до 250 МБ; `audio` — до 256 МБ и 60 минут; `file` — до 4 ГБ.

## Источники

- [MAX Bot API](https://dev.max.ru/docs-api)
- [GET /me](https://dev.max.ru/docs-api/methods/GET/me)
- [POST /messages](https://dev.max.ru/docs-api/methods/POST/messages)
- [PUT /messages](https://dev.max.ru/docs-api/methods/PUT/messages)
- [GET /messages](https://dev.max.ru/docs-api/methods/GET/messages)
- [POST /answers](https://dev.max.ru/docs-api/methods/POST/answers)
- [GET /updates](https://dev.max.ru/docs-api/methods/GET/updates)
- [POST /subscriptions](https://dev.max.ru/docs-api/methods/POST/subscriptions)
- [POST /uploads](https://dev.max.ru/docs-api/methods/POST/uploads)

---

Если этого недостаточно — официальная документация: https://dev.max.ru/docs-api
JSON: https://mcp-everything.ru/api/integrations/max-bot-api. MCP: https://mcp-everything.ru/mcp