Обзор

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

Пример клавиатуры Пример клавиатуры

Клавиатуру можно настраивать: количество кнопок, подписи, цвета и действия. Это позволяет строить меню и сценарии, которые зависят от контекста диалога.

Типы клавиатур

Поле inline в объекте, описывающем клавиатуру, указывает тип клавиатуры.

Клавиатура чата

Если "inline": false, то клавиатура располагается под полем ввода текста в окне чата.

inline: false. Клавиатура под полем ввода inline: false. Клавиатура под полем ввода

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

•
До 40 кнопок.
•
До 10 рядов по 5 кнопок.

Inline-клавиатура

Если "inline": true, клавиатура показывается в поле сообщения.

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

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

•
До 10 кнопок.
•
До 6 рядов по 5 кнопок.

Общие правила отображения

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

Параметры клавиатуры

Клавиатура передаётся в параметре keyboard метода messages.send в виде JSON-строки.

Пример:

JSON

{
  "inline": false,
  "one_time": false,
  "buttons": [
    [
      {
        "action": {
          "type": "text",
          "label": "Помощь",
          "payload": "{\"cmd\":\"help\"}"
        },
        "color": "secondary"
      }
    ]
  ]
}

Объект клавиатуры

Поле	Тип	Описание
`buttons` обязательное	`array`	Массив рядов. Каждый ряд — массив кнопок.
`one_time`	`bool`	Скрывать клавиатуру после нажатия (`true/false`). Работает только при `inline: false`.
`inline`	`bool`	Тип клавиатуры: `false` — под полем ввода, `true` — внутри сообщения.

Объект кнопки

Поле	Тип	Описание
`action` обязательное	`object`	Действие кнопки. Типы действий описаны в разделе Типы кнопок.
`color`	`string`	Цвет кнопки. Используется только для кнопок `text` и `callback`.

Цвета кнопок

Значение	Назначение	Цвет в светлой теме	Цвет в тёмной теме
`primary`	Основное действие	`#5181B8`	`#E1E3E6`
`secondary`	Обычная кнопка	`#E5EBF1`	`#424242`
`negative`	Отмена/опасное действие	`#E64646`	`#FF5C5C`
`positive`	Подтверждение	`#4BB34B`	`#4BB34B`

Особенности работы

•

Чтобы убрать клавиатуру из чата, отправьте пустой набор кнопок в параметре keyboard:

JSON
{ "buttons": [] }
•

Проверяйте payload на сервере. Значения payload, указанные в кнопках, приходят в событиях бота. Пользователь может подменить payload вручную, поэтому проверяйте входящие данные и обрабатывайте только допустимые значения.
•

Если в настройках сообщества включена кнопка «Начать», то при первом диалоге пользователь отправит команду start. payload будет выглядеть так:

JSON
{"command":"start"}