Клавиатура

Подключение

Чтобы включить клавиатуры в сообществе, перейдите в Управление сообществом → Сообщения → Настройки для бота и включите Возможности ботов. Там же можно добавить кнопку Начать.

Кнопка «Начать»

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

{"command":"start"}

Внешний вид

Клавиатура представляет собой массив массивов, то есть таблицу, у которой ячейки — это кнопки. У всех кнопок в рамках одной строки одинаковый размер, и они заполняют 100% ширины. Высота всех кнопок — константа. Текст отображается по центру кнопки и обрезается, если не помещается полностью при текущем размере экрана.

Стандартное отображение

По умолчанию, если не передан параметр inline, клавиатура показывается под полем ввода в диалоге с пользователем. Максимальный размер стандартной клавиатуры — 5 × 10. Максимальное количество клавиш: 40.

Inline-отображение

Клавиатура может отображаться внутри сообщения — это inline-отображение. Чтобы включить его, передайте параметр inline в объект клавиатуры. Её максимальный размер составит 5 × 6. Максимальное количество клавиш: 10.

Структура данных

`one_time`

bool Скрывать ли клавиатуру после первого использования. Параметр срабатывает только для кнопок, отправляющих сообщение (поле type - text, location) Для type равных open_app, vk_pay параметр игнорируется. Возможные значения:

•
true — клавиатура будет скрыта при нажатии на кнопку с типом text или location;
•
false — клавиатура не скрывается;

`buttons`

array Массив массивов с кнопками.

`inline`

bool Должна ли клавиатура отображаться внутри сообщения. Возможные значения:

•
true — клавиатура отображается внутри сообщения. Параметр one_time при этом не поддерживается;
•
false — стандартное отображение клавиатуры.

`action`

object Объект, описывающий тип действия и его параметры. Поля объекта зависят от значения параметра type и описаны в таблице ниже.

`color`

string Цвет кнопки. Параметр используется только для кнопок с type: text и callback. Возможные значения:

•
primary — синяя кнопка, обозначает основное действие. #5181B8
•
secondary — обычная белая кнопка. #FFFFFF
•
negative — опасное действие, или отрицательное действие (отклонить, удалить и тд). #E64646
•
positive — согласиться, подтвердить. #4BB34B

Поля объекта action в зависимости от типа кнопки.

`Text`

Текстовая кнопка. Отправляет сообщение c текстом, указанным в label. Поля текстовой кнопки:

•
type (string) — для текстовой кнопки имеет значение text;
•
label (string) — текст кнопки. Будет отправлен пользователем в диалог с сообществом/беседу при нажатии;
•
payload (string) — дополнительная информация. Вернется в событии message_new в одноименном поле. Максимум 255 символов.

`Open Link`

Открывает указанную ссылку. Поля:

•
type (string) — для кнопки открытия ссылки имеет значение open_link;
•
link (url) — ссылка, которую необходимо открыть по нажатию на кнопку;
•
label (string) — текст кнопки;
•
payload (string) — дополнительная информация. В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.

`Location`

По нажатию отправляет местоположение в диалог с ботом/беседу. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:

•
type (string) — для кнопки местоположения имеет значение location;
•
payload (string) — дополнительная информация. Вернется в событии message_new в одноименном поле. Максимум 255 символов.

`VK Pay`

Открывает окно оплаты VK Pay с предопределёнными параметрами. Кнопка называется «Оплатить через VK pay», VK pay отображается как логотип. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:

•
type (string) — для кнопки вызова платежного окна имеет значение vkpay;
•
payload (string) — дополнительная информация. В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.
•
hash (string) — строка, содержащая параметры платежа VK Pay и идентификатор приложения в параметре aid , разделенные &. Пример: action=transfer-to-group&group_id=1&aid=10.

`VK Apps`

Открывает указанное приложение VK Apps. Эта кнопка всегда занимает всю ширину клавиатуры. Поля:

•
type (string) — для кнопки открытия сервиса имеет значение open_app;
•
app_id (int) — идентификатор вызываемого приложения с типом VK Apps.
•
owner_id (int) — идентификатор сообщества, в котором установлено приложение, если требуется открыть в контексте сообщества;
•
payload (string) — дополнительная информация. В кнопках, не отправляющих текст, передается для совместимости со старыми клиентами. Максимум 255 символов.
•
label (string) — название приложения, указанное на кнопке.
•
hash (string) — хеш для навигации в приложении, будет передан в строке параметров запуска после символа #.

`Callback`

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

•
type (string) — для callback-кнопки имеет значение callback;
•
label (string) — текст кнопки.
•
payload (string) — дополнительная информация. В кнопках, не отправляющих текст, передаётся для совместимости со старыми клиентами. Максимум 255 символов. Подробнее читайте в разделе Callback-кнопки.

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

JSON

{  
   "one_time":false,
   "buttons":[  
      [  
         {  
            "action":{  
               "type":"location",
               "payload":"{\"button\": \"1\"}"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"open_app",
               "app_id":6232540,
               "owner_id":-157525928,
               "hash":"123",
               "label":"LiveWidget"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"vkpay",
               "hash":"action=transfer-to-group&group_id=181108510&aid=10"
            }
         }
      ],
      [  
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"1\"}",
               "label":"Red"
            },
            "color":"negative"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"Green"
            },
            "color":"positive"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"Blue"
            },
            "color":"primary"
         },
         {  
            "action":{  
               "type":"text",
               "payload":"{\"button\": \"2\"}",
               "label":"White"
            },
            "color":"secondary"
         }
      ]
   ]
}

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

JSON-объект клавиатуры передается строкой в параметре keyboard в методе messages.send с последней версией API.

Как только пользователь нажимает на одну из кнопок клавиатуры, отправляется сообщение с текстом из поля label. Если задан параметр payload, он дополнительно придет в callback API.

Важное замечание: чтобы получать параметр payload, нужно поднять версию callback API до 5.69 или выше. Параметр payload нужно передавать в формате JSON.

Пример события в Callback API

JSON

{
    "type": "message_new",
    "object": {
        "id": 41,
        "date": 1526898082,
        "out": 0,
        "user_id": 163176673,
        "read_state": 0,
        "title": "",
        "body": "Blue",
        "payload": "{\"button\":\"4\"}"
    },
    "group_id": 1
}

Также, если клавиатура была определена с флагом one_time, она сразу же скрывается. Если нет, остается как была и пользователь может отправить еще сколько угодно команд. Чтобы убрать у пользователя клавиатуру, необходимо отправить сообщение с пустым параметром buttons:

JSON{"buttons":[],"one_time":true}

Callback-кнопки

Callback-кнопки — тип кнопок, который работает в стандартном и в inline-отображении клавиатур ботов.

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

Примеры использования

•
Реализация основного меню бота: после нажатия на callback-кнопку на клавиатуре бот обновляет её, выполняя переход на уровень глубже по вложенности меню. При этом пользователю не нужно отправлять боту дополнительное сообщение.
•
Редактирование сообщения: пользователь нажимает на callback-кнопку в inline-клавиатуре из сообщения, выбирая категорию блюда в меню, — бот редактирует сообщение, предлагая блюда из этой категории. Пользователь при этом не отправляет боту сообщение.
•
Отправка результата действия: пользователь нажимает на callback-кнопку, например «Пополнить баланс», которая совершает определённое действие. После его успешного выполнения бот показывает пользователю информацию «Баланс пополнен» при помощи snackbar. Отправка сообщения при этом не требуется.

Принцип работы

JSON

{
  action: {
    type: "callback",
    payload: "{}", // максимум 255 символов
    label: "Нажми меня"
  }
}

•
пользователь нажимает на клавишу;
•
бот получает новое событие message_event в Callback или LongPoll API:

JSON

{
  "conversation_message_id": 1234,
  "user_id": 612512941,   // id пользователя, который нажал на кнопку
  "peer_id": 2000000094, // id диалога со стороны бота
  "event_id": "feleyinek", // Случайная строка. Активна в течение минуты, спустя минуту становится недействительной
  "payload": "{}"
}

•
бот формирует запрос к API, используя метод messages.sendMessageEventAnswer;
•
клиент пользователя получает ответ от бота и выполняет нужное действие.

Действие после нажатия на кнопку

Бот отправляет event_data — объект действия, которое должно произойти после нажатия на кнопку.

JSON

{
    "type": "show_snackbar",
    "text": "Покажи исчезающее сообщение на экране"
  }

Метод messages.sendMessageEventAnswer можно выполнить только один раз за нажатие на клавишу.

Типы действий

1.
show_snackbar — показать исчезающее сообщение. Содержит поле text — текст, который нужно вывести (максимум 90 символов). Snackbar показывается в течение 10 секунд и автоматически скрывается, при этом у пользователя есть возможность смахнуть его с экрана.
2.
open_link — открыть ссылку. Осуществляется переход по указанному адресу.
JSON{ type: "open_link", link: url }
3.
open_app — открыть VK Mini App. Происходит переход в мини-приложение.
JSON{ type: "open_app", app_id: int, owner_id: int | null, hash: string }

Внешний вид

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

Обработка ошибок

Если в формате объекта клавиатуры есть ошибки, messages.send вернёт ошибку 911. Keyboard format is invalid.