Кнопки в чат-боте MAX: inline-клавиатура через API

Обновлено 20 октября 2026 г.3 мин

Продолжение гайда «Первый чат-бот MAX через API». Все лимиты и поля взяты из документации dev.max.ru.

Как отправить сообщение с кнопками

Кнопки — это вложение типа inline_keyboard в запросе POST /messages. Каждый ряд — это массив внутри payload.buttons, и у каждой кнопки обязательно поле text:

curl -X POST "https://platform-api2.max.ru/messages?user_id=USER_ID" \
  -H "Authorization: $MAX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Что дальше?",
    "attachments": [{
      "type": "inline_keyboard",
      "payload": { "buttons": [
        [ { "type": "callback", "text": "Подтвердить", "payload": "confirm" } ],
        [ { "type": "link", "text": "Сайт", "url": "https://example.com" } ]
      ] }
    }]
  }'

Вместе с клавиатурой можно отправить и другие вложения: фото, видео, контакт.

Лимиты клавиатуры

До 210 кнопок: 30 рядов по 7 кнопок в каждом.
В ряду с кнопками link, open_app, request_geo_location или request_contact — не больше 3 кнопок.
Кнопки в одном ряду всегда одинаковой ширины. Длинный текст обрезается, поэтому подписи делайте короткими.
Если переслать сообщение с кнопками в другой чат, кнопки не перешлются.

Типы кнопок

Тип	Что делает	Пример
`callback`	Присылает боту событие `message_callback`	Подтвердить заказ
`link`	Открывает ссылку длиной до 2048 символов	Оплата на сайте, каталог
`message`	Отправляет боту заданный текст от имени пользователя	Быстрый ответ, команда
`request_contact`	Запрашивает контакт и номер телефона	Регистрация
`request_geo_location`	Запрашивает местоположение	Доставка, ближайший офис
`open_app`	Открывает мини-приложение бота	Калькулятор, анкета
`clipboard`	Копирует `payload` в буфер обмена	Промокод, трек-номер

Как ответить на нажатие callback

Бот получает событие message_callback через Webhook или Long Polling. В событии есть callback_id, и с ним бот вызывает POST /answers. Ответом может быть обновлённое сообщение и/или одноразовое уведомление пользователю (dev.max.ru):

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": "Заказ подтверждён" } }'

Лимит — не больше двух ответов в секунду в один чат. Лишние ответы ставьте в очередь. Для продакшена документация рекомендует Webhook: у Long Polling ограничены скорость и срок хранения событий.

Номер телефона через request_contact

Сообщение с контактом от этой кнопки содержит поле hash. По нему можно проверить, что номер совпадает с номером аккаунта в MAX:

hash = HMAC-SHA256(access_token, vcf_info), где ключ — токен бота.
Перед хешированием замените экранированные \r\n в vcf_info на настоящие переносы строк.
Если пользователь отправил контакт другим способом (через 📎 или из телефонной книги), поля hash не будет, и подтвердить номер не получится.

Номер, полученный таким способом, можно использовать только для работы этого бота: регистрация, программа лояльности, статус заказа (dev.max.ru). Номер в мини-приложении запрашивается иначе — через MAX Bridge.

Если кнопки не работают

Нажатие на callback ничего не делает — бот не получает события. Проверьте подписку: почему не приходят уведомления на webhook.
Кнопки не видны в пересланном сообщении — так и должно быть: при пересылке кнопки не сохраняются.
Ошибка при отправке — проверьте лимит в 3 кнопки в ряду для link, open_app, request_contact и request_geo_location.

Недавние запросы

Часто ищут

Разделы