Custom keyboards are essentially toolbars containing one or more user defined buttons. The keyboards provide alternative means of input, allowing a user to communicate with a chatbot by clicking the buttons.
Adding a Keyboard to a Chatbot
A keyboard is actually part of a chatbot message. To create a keyboard, you have to specify a KEYBOARD key with parameters defining the keyboard layout.
The following methods support the KEYBOARD key:
- imbot.message.add - sends chatbot message.
- imbot.message.update - updates (changes) chatbot message.
- imbot.command.answer - provides reaction to keyboard input.
- im.message.add - sends message to the chat.
- im.message.update - updates (changes) chatbot message in the chat.
Consider the following example:
restCommand('imbot.command.answer', Array( "COMMAND_ID" => $command['COMMAND_ID'], "MESSAGE_ID" => $command['MESSAGE_ID'], "MESSAGE" => "Hello! My name is EchoBot :)[br] I am designed to answer your questions!", "KEYBOARD" => Array( Array( "TEXT" => "Bitrix24", "LINK" => "http://bitrix24.com", "BG_COLOR" => "#29619b", "TEXT_COLOR" => "#fff", "DISPLAY" => "LINE", ), Array( "TEXT" => "BitBucket", "LINK" => "https://bitbucket.org/Bitrix24com/rest-bot-echotest", "BG_COLOR" => "#2a4c7c", "TEXT_COLOR" => "#fff", "DISPLAY" => "LINE", ), Array("TYPE" => "NEWLINE"), // line break Array("TEXT" => "Echo", "COMMAND" => "echo", "COMMAND_PARAMS" => "test from keyboard", "DISPLAY" => "LINE"), Array("TEXT" => "List", "COMMAND" => "echoList", "DISPLAY" => "LINE"), Array("TEXT" => "Help", "COMMAND" => "help", "DISPLAY" => "LINE"), ) ), $_REQUEST["auth"]);
Each button in the keyboard is defined by the following keys:
- TEXT - specifies the button text;
- LINK - specifies a hyperlink;
- COMMAND - a command to send to the bot;
- COMMAND_PARAMS - specifies command parameters;
- BG_COLOR - specifies the button color;
- BLOCK - if set to Y, the keyboard will be disabled after this button is clicked;
- DISABLED - specify Y to disable the button;
- TEXT_COLOR - specifies the button text color;
- DISPLAY - specifies the button layout in the row. If set to BLOCK, only this button can occupy the row. If set to LINE, the buttons will be aligned one after the other;
- WIDTH - button width in pixels. Try to avoid making buttons wider than 255 pixels, because it's the maximum width on mobile devices.
- APP_ID - specifies the ID of an installed chat application.
- APP_PARAMS - parameters that will be passed over to the chat application.
- ACTION - action can have the following type (REST revision 28):
- PUT - enter into input field.
- SEND - send text.
- COPY - copy text to clipboard.
- CALL - call.
- DIALOG - open specified dialog.
- ACTION_VALUE - each type has its own value (REST revision 28):
- PUT - text inserted into input field.
- SEND - text to be sent.
- COPY - text copied to clipboard.
- CALL - phone number in the international format.
- DIALOG - dialog ID. Can be both user ID or chat ID in format
The TEXT key is required. To perform sensible action, one of the LINK and COMMAND keys are required as well.
If the LINK key is not empty, the button is treated as an external link. If COMMAND and COMMAND_PARAMS keys are specified, the button sends command to the bot.
If the APP_ID and APP_PARAMS keys are specified, the button will open a chat application window.
To start a new row of buttons, add a button containing only one key:
"TYPE" => "NEWLINE".
Command Processing on the Chatbot Side
Chatbots use commands to process button clicks.
- To make a command recognizable, it has to be registered using the imbot.command.register
(method in the ONAPPINSTALL event handler. To make the command available only from the keyboard, add the
"HIDDEN" => "Y"key).
Use these keys in the button description to fire a command:
"COMMAND" => "page", // command to send to chatbot "COMMAND_PARAMS" => "1", // command parameters
Button click will generate ONIMCOMMANDADD event.
1. In the event handler, create a new message as a response or update an existing message (effectively creating page-by-page navigation feature).
- The [data][COMMAND] array passed to the event handler will contain the event information. This array now contains a new key, COMMAND_CONTEXT to describe calling context:
- TEXTAREA for commands posted by user by typing in from the device keyboard;
- KEYBOARD for commands originating from the chatbot keyboard or a context menu.
Application Launch Processing for Chatbot
Application for chat, launched from context menu, is working based on principles of Context Application.
Further Usage Examples
Page navigation; custom buttons are shown when user executes the Help command
Use the More button to get more images for the specified keyword: