Просмотров: 28211
Дата последнего изменения: 20.08.2024
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
4
5
Набираемые клавиатуры позволят пользователю взаимодействовать с чат-ботом, просто нажимая на кнопки.
Как клавиатуру добавить к чат-боту
Клавиатура — это часть сообщения, при создании сообщения нужно добавить ключ KEYBOARD и передать параметры.
Методы, которые поддерживают клавиатуру:
Рассмотрим на примере сообщения чат-бота. В веб-версии чата клавиатура выглядит так:
А в мобильной версии так:
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"]
);
Примечание: функция
restCommand — это метод отправки данных в
Битрикс24, данный метод есть в примере
ЭхоБота, и представлен здесь в качестве примера. Вы можете использовать свою функцию или javascript-метод
BX24.callMethod или
bitrix24-php-sdk.
Клавиатура — это набор кнопок, каждая кнопка может состоять из следующих ключей:
- 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"
.
Обработка команд чат-ботом
Для обработки нажатия кнопок клавиатуры, используются команды.
- Для того, чтобы команда отрабатывала в клавиатуре (и не только), необходимо ее предварительно зарегистрировать через метод imbot.command.register
(чтобы команда была доступна только для клавиатуры, необходимо создать ее с ключом
"HIDDEN" => "Y"
).
В кнопке указывается следующие ключи:
"COMMAND" => "page", // команда, которая будет отправлена чат-боту
"COMMAND_PARAMS" => "1", // параметры для команды
Нажатие на кнопку сгенерирует событие ONIMCOMMANDADD.
Внутри этого события нужно либо создать новое сообщение, либо отредактировать старое (тем самым формируя эффект постраничной навигации).
- Внутри события, в массиве [data][COMMAND] будут переданы данные о вызванном событии. В нем есть значение COMMAND_CONTEXT — это специальный ключ, описывающий в каком контексте была вызвана команда:
- если команду написал пользователь самостоятельно, там будет TEXTAREA;
- если команда пришла из клавиатуры, то будет KEYBOARD;
- если команда пришла из контекстного меню, то будет MENU.
Готовый пример, можно посмотреть в обновленной версии ЭхоБота (bot.php).
Обработка открытия приложения для чата
Приложение для чата, запускаемые из контекстного меню, работают по принципам Контекстного приложения.
Примеры использования клавиатуры
- EchoBot
Постраничная навигация, кнопки при вызове команды «Помощь»
- Марта
Просто напишите марте Поиграй со мной!. Клавиатура используется как игровое поле:
- Giphy
Кнопка Еще позволяет без повторного введения поискового слова просматривать другие картинки на эту же тему: