Клавиатура в сообщениях

Для более удобного взаимодействия пользователя с ботом можно использовать inline-клавиатуру. Она встраивается прямо в сообщение и содержит заранее настроенные кнопки. Пользователь может отправлять боту запросы, просто нажимая на эти кнопки, вместо того чтобы печатать текст вручную

Если переслать сообщение с кнопками из чат-бота в любой другой чат, кнопки не будут пересланы

Чтобы отправить сообщение c клавиатурой в чат или канала через API, используйте метод POST /messages, в массиве attachments укажите type = inline_keyboard

Вместе с клавиатурой вы можете отправить и другие вложения, например, изображения, видео, аудио, контакты. Подробнее — в разделах «Отправка сообщений с медиафайлами», «Как отправить несколько медиафайлов», «Стикеры и контакты»

Проектирование клавиатуры

Inline-клавиатура позволяет разместить под сообщением бота до 210 кнопок, сгруппированных в 30 рядов — до 7 кнопок в каждом (до 3, если это кнопки типа link, open_app, request_geo_location или request_contact)

При проектировании клавиатуры учитывайте следующие особенности отображения:

Текст на кнопке выравнивается по центру и обрезается, если выходит за её границы
Кнопки в одной строке всегда одинаковой ширины
Ширина каждого ряда кнопок равна ширине клавиатуры
Высота у всех кнопок по умолчанию одинаковая

Типы кнопок

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

Тип кнопки	Описание	Примеры использования
`callback`	Сервер MAX отправляет событие с типом `message_callback`, если вы подписаны на обновления через Webhook или Long Polling. Подробнее о рекомендациях и ограничениях при работе с Webhook и Long Polling — в разделе «Рекомендации по работе с API»	Выбрать товар, подтвердить действие пользователя
`link`	Открывает ссылку в новой вкладке. Длина ссылки ограничена 2048 символами	Открыть сайт, соцсеть, онлайн-оплату, статью, каталог или форму
`request_contact`	Запрашивает у пользователя его контакт и номер телефона	Зарегистрироваться и авторизоваться в боте, заказать обратный звонок, привязать номер телефона к системе лояльности
`request_geo_location`	Запрашивает у пользователя его местоположение	Оформить доставку, найти ближайший офис, посмотреть погоду
`open_app`	Открывает мини-приложение внутри чат-бота	Открыть конструктор, калькулятор, опросник
`message`	Отправляет боту заранее заданный текст	Отправить быстрый ответ, команду, шаблонное сообщение
`clipboard`	Копирует текст, указанный в свойстве `payload`, в буфер обмена	Скопировать промокод, номер карты, адрес, артикул, трек-номер

Как добавить кнопки

Чтобы добавить кнопки, отправьте сообщение POST-методом /messages

В теле запроса передайте объект attachments с типом inline_keyboard и массивом кнопок payload.buttons. Для каждой кнопки обязательно укажите её текст в параметре text. Также в зависимости от типа кнопки могут потребоваться и другие параметры

Одна кнопка

Несколько кнопок в столбце

Несколько кнопок в строке

JSON

Скопировать

{
  "text": "Это сообщение с кнопкой-ссылкой",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "link",
              "text": "Откройте сайт",
              "url": "https://example.com"
            }
          ]
        ]
      }
    }
  ]
}

Как добавить клавиатуру с помощью библиотек, читайте в разделе «Библиотека JavaScript»

Кнопка request_contact

При нажатии на кнопку с типом request_contact пользователь отправит в чат-бот свой контакт и номер телефона, привязанный к аккаунту в МАКС

Сообщение с контактом содержит поле hash — оно позволяет проверить, что пользователь поделился номером телефона, совпадающим с его номером в МАКС. Благодаря этому получение номера пользователя через сообщение с типом request_contact можно использовать, например, как способ регистрации в чат-боте

Данные пользователя (включая номер телефона), полученные с помощью кнопки request_contact, могут использоваться только для взаимодействия с текущим чат-ботом. Например, их можно применять для регистрации в программе лояльности, проверки статуса заказа, идентификации в рамках сервиса бота

Обратите внимание: отправка номера телефона в мини-приложение описана на странице MAX Bridge

Другие способы отправки контакта в чат-бот

Если отправить номер телефона в диалог с чат-ботом другим способом, например, поделиться через 📎 в интерфейсе МАКС или переслать из телефонной книги, сообщение не будет содержать поля hash. В этом случае подтвердить, что номер принадлежит пользователю, не получится

Возможный сценарий взаимодействия пользователя и чат-бота

Чат-бот отправляет пользователю запрос POST /messages с кнопкой типа request_contact
Пользователь получает сообщение с кликабельной кнопкой Поделиться контактом
Пользователь нажимает на кнопку, тем самым отправляя в чат-бот свой номер телефона в МАКС
Чат-бот получает номер телефона пользователя из сообщения — запрос GET /messages
Чат-бот проверяет, что полученный в сообщении номер телефона совпадает с номером, привязанным к аккаунту пользователя в МАКС. Для этого сравнивает:
- Значение поля hash, полученное в сообщении в массиве attachments.payload:
  JSON
  Скопировать
  "attachments": [ { "payload": { "vcf_info": "string", // Строковая информация о пользователе "max_info": { // Информация о пользователе }, "hash": "string" // Хеш информации о пользователе из поля `vcf_info` }, "type": "contact" } ]
- Значение функции HMAC-SHA256(access_token, vcf_info), где:
  - HMAC-SHA256 — стандартная для большинства языков программирования криптографическая функция
  - access_token — токен чат-бота
  - vcf_info — информация о контакте в формате:
  Код
  Скопировать
  "vcf_info": "BEGIN:VCARD\r\nVERSION:3.0\r\nPRODID:ez-vcard 0.10.3\r\nTEL;TYPE=cell:79990000000\r\nFN:Ivan Ivanov\r\nEND:VCARD\r\n"
  Если значения совпадают, это подтверждает, что пользователь поделился номером телефона, привязанным к его аккаунту в МАКС
  Обратите внимание: перед хешированием необходимо преобразовать символы \r\n поля vcf_info в реальные переносы строк

Кнопка clipboard

При нажатии на кнопку с типом clipboard текст, указанный в свойстве payload, копируется в буфер обмена

В свойстве payload можно передать любой текст, например промокод, трек-номер, платёжные реквизиты

JSON

Скопировать

{
  "type": "clipboard", // Тип кнопки
  "text": "Скопировать", // Текст кнопки
  "payload": "123456" // Текст, который будет скопирован
}

Если у вас возникли вопросы, посмотрите раздел с ответами