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

Сценарий из mcp-everything. Актуально на 2026-10-24.

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

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 подтверждён"}}'
```

## Базовые 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}"
```

## Методы сценария

### 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 |

### 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 /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`.

## Другие сценарии

- [Отправить сообщение пользователю или в чат](https://mcp-everything.ru/integrations/max-bot-api/scenarios/otpravit-soobschenie-polzovatelyu-ili.md)
- [Принимать сообщения через вебхук](https://mcp-everything.ru/integrations/max-bot-api/scenarios/prinimat-soobscheniya-cherez-vebhuk.md)
- [Бот без сервера: long polling для разработки](https://mcp-everything.ru/integrations/max-bot-api/scenarios/bot-bez-servera-long-polling-dlya.md)
- [Отправить файл или картинку](https://mcp-everything.ru/integrations/max-bot-api/scenarios/otpravit-fayl-ili-kartinku.md)

---

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