При разработке и поддержке проектов на платформе 1С-Битрикс критически важно использовать современные стандарты D7 API. В этом руководстве мы детально изучим тему «Работа с клавиатурами», разберем архитектурные особенности и предоставим готовые к интеграции примеры кода.

Работа с клавиатурами

Тут может не хватать некоторых данных — дополним в ближайшее время

• нужны правки под стандарт написания

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

Как клавиатуру добавить к чат-боту

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

Методы, которые поддерживают клавиатуру:

• imbot.message.add — отправка сообщения от чат-бота.
• imbot.message.update — отправка изменения сообщения чат-бота.
• imbot.command.answer — публикация ответа на команду.
• im.message.add — отправка сообщения в чат.
• im.message.update — отправка изменения сообщения чат-бота.

Рассмотрим на примере сообщения чат-бота. В веб-версии чата клавиатура выглядит так:

!keyboard example

А в мобильной версии так:

!keyboard example

• PHP

    restCommand(
        'imbot.command.answer',
        Array(
            "COMMAND_ID" => $command['COMMAND_ID'],
            "MESSAGE_ID" => $command['MESSAGE_ID'],
            "MESSAGE" => "Hello! My name is EchoBot :)[br] I designed to answer your questions!",
            "KEYBOARD" => Array(
    // Синяя кнопка с текстом Bitrix24 на первой строке
                Array(
                    "TEXT" => "Bitrix24",
                    "LINK" => "http://bitrix24.com",
                    "BG_COLOR_TOKEN" => "primary",
                    "BG_COLOR" => "#29619b",
                    "TEXT_COLOR" => "#fff",
                    "DISPLAY" => "LINE",		
                ),
    // Белая кнопка с текстом BitBucket на первой строке
                Array(
                    "TEXT" => "BitBucket", 
                    "LINK" => "https://bitbucket.org/Bitrix24com/rest-bot-echotest",
                    "BG_COLOR_TOKEN" => "secondary",
                    "BG_COLOR" => "#2a4c7c",
                    "TEXT_COLOR" => "#fff",
                    "DISPLAY" => "LINE",
                ),
    // перенос строки, следующие кнопки будут размещены на второй строке
                Array(
                    "TYPE" => "NEWLINE" 
                ), 
    // Красная кнопка с текстом Echo на второй строке
                Array(
                    "TEXT" => "Echo", 
                    "COMMAND" => "echo",
                    "COMMAND_PARAMS" => "test from keyboard",
                    "DISPLAY" => "LINE",
                    "BG_COLOR_TOKEN" => "alert",
                ),
    // Базовая кнопка с текстом List на второй строке
                Array(
                    "TEXT" => "List",
                    "COMMAND" => "echoList",
                    "DISPLAY" => "LINE"
                ),
    // Базовая кнопка с текстом Help на второй строке
                Array(
                    "TEXT" => "Help", 
                    "COMMAND" => "help",
                    "DISPLAY" => "LINE"
                ),
            )
        ),
        $_REQUEST["auth"]
    );

Клавиатура — это набор кнопок, каждая кнопка может состоять из следующих ключей:

• TEXT — текст кнопки
• LINK — ссылка
• COMMAND — команда, которая будет отправлена боту
• COMMAND_PARAMS — параметры для команды
• BG_COLOR_TOKEN — токен для цвета кнопки в чате. Может принимать одно из следующих значений:
• primary
• secondary
• alert
• base

По умолчанию имеет значение base

• BG_COLOR — цвет кнопки в формате HEX-кода. Используется для обратной совместимости в кнопках чатов открытых линий
• BLOCK — если указать Y, то после клика на одну кнопку клавиатура будет блокироваться. Клавиатуру блокируют только кнопки, которые отправляют ajax боту (учтите, что ссылки на внешние ресурсы LINK и мгновенные действия ACTION не блокируют клавиатуру). Блокировка нужна для ограничения выполнения ajax-команд из-за их асинхронности и времени ожидания: после нажатия кнопки клавиатура блокируется и ожидается реакция с бэкенда Битрикс24, чтобы пользователь не нажал вторую кнопку и т. д. Бэкенд обрабатывает команды и принимает решение, разблокировать ли клавиатуру, создав новую, или же скрыть её
• DISABLED — если указать Y, то данная кнопка не будет кликабельной
• TEXT_COLOR — цвет текста кнопки в формате HEX-кода. Используется для обратной совместимости в кнопках чатов открытых линий
• DISPLAY — тип кнопки. Если указан тип BLOCK, то на одной строчке может быть только эта кнопка. Если указан тип LINE, то кнопки будут выстроены друг за другом
• WIDTH — ширина кнопки. Обратите внимание, для максимального удобства набор кнопок в одну линию не рекомендуется делать более 225 пикселей, это максимальная ширина на мобильном устройстве
• APP_ID — идентификатор установленного приложения для чата
• APP_PARAMS — параметры для запуска приложения для чата
• ACTION — действие, может быть одно из следующих типов (REST ревизии 28):
• PUT — вставить в поле ввода
• SEND — отправить текст
• COPY — копировать текст в буфер обмена
• CALL — позвонить
• DIALOG — открыть указанный
• ACTION_VALUE — значение, для каждого типа означает свое (REST ревизии 28):
• PUT — текст, который будет вставлен в поле ввода
• SEND — текст, который будет отправлен
• COPY — текст, который будет скопирован в буфер обмена
• CALL — номер телефона в международном формате
• DIALOG — идентификатор диалога, это может быть ID пользователя, либо ID чата в формате chatXXX

Обязательными полями является TEXT и либо поле LINK, либо поле COMMAND.

Если указан ключ LINK, то кнопка становится внешней ссылкой. Если указаны поля COMMAND и COMMAND_PARAMS, то кнопка является действием и отправляет команду чат-боту, не публикуя ее в чат.

Если указаны поля APP_ID и APP_PARAMS, то кнопка откроет окно с приложением для чата.

Если необходимо сделать две строки с кнопками в ряд, то для их разделения нужно добавить кнопку со следующим содержимым: "TYPE" => "NEWLINE".

Обработка команд чат-ботом

Для обработки нажатия кнопок клавиатуры, используются команды.

1. Для того, чтобы команда отрабатывала в клавиатуре (и не только), необходимо ее предварительно зарегистрировать через метод imbot.command.register (чтобы команда была доступна только для клавиатуры, необходимо создать ее с ключом "HIDDEN" => "Y").

В кнопке указывается следующие ключи:

    "COMMAND" => "page", // команда, которая будет отправлена чат-боту
    "COMMAND_PARAMS" => "1", // параметры для команды

2. Нажатие на кнопку сгенерирует событие ONIMCOMMANDADD.

3. Внутри этого события нужно либо создать новое сообщение, либо отредактировать старое (тем самым формируя эффект постраничной навигации).

4. Внутри события, в массиве [data][COMMAND] будут переданы данные о вызванном событии. В нем есть значение COMMAND_CONTEXT — это специальный ключ, описывающий в каком контексте была вызвана команда:

• если команду написал пользователь самостоятельно, там будет TEXTAREA;
• если команда пришла из клавиатуры, то будет KEYBOARD;
• если команда пришла из контекстного меню, то будет MENU.

Готовый пример, можно посмотреть в обновленной версии ЭхоБота (bot.php).

Обработка открытия приложения для чата

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

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

1. EchoBot
Постраничная навигация, кнопки при вызове команды «Помощь»

2. Марта
Просто напишите марте «Поиграй со мной!». Клавиатура используется как игровое поле:

3. Giphy
Кнопка Еще позволяет без повторного введения поискового слова просматривать другие картинки на эту же тему:

!Giphy Keyboard