Bitrix24 Bot Platform

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
• Command Processing by Chatbot
• Examples

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. Only the buttons that send ajax commands to bot can block the keyboard (be advised, that Links to third-party resources and instant Actions do not block the keyboard). Blocking is needed to limit execution of ajax commands due to their asynchronicity and standby time: the keyboard is blocked after clicking the button and Bitrix24 backend reaction standby is ON, so that user couldn't click on second button, etc. Backend processes commands and decides, whether to unblock the keyboard, hide it or create new one;
• 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 chatXXX.

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.

1. 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
   

2. Button click will generate ONIMCOMMANDADD event.

3. 1. In the event handler, create a new message as a response or update an existing message (effectively creating page-by-page navigation feature).

4. 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.
   • MENU for commands originating from context menu.

You can find an updated EchoBot example here, example (bot.php).




Application Launch Processing for Chatbot

Application for chat, launched from context menu, is working based on principles of Context Application.

Examples

1. Giphy
   Use the More button to get more images for the specified keyword: