Bitrix24 Bot Platform

A context menu allows for chatbot-to-user interaction from the message context menu.

• Adding Custom Items to the Context Men
• Command Processing on the Chatbot Side
• Processing of App launch for chat

Adding Custom Items to the Context Menu

A context menu is part of a chatbot message. To add custom menu items, you have to specify MENU key.

The following methods support the Menu:

• imbot.message.add - sends a chatbot message.
• imbot.message.update - updates (changes) the chatbot message.
• imbot.command.answer - provides reaction to keyboard input.
• im.message.add - sends a message to the chat.
• im.message.update - updates (changes) the chatbot message in the chat.

Consider the following example:

restCommand('im.message.add', Array(
   "DIALOG_ID" => 12,
   "MESSAGE" => "Hello! Message with context menu!",
   "MENU" => Array(
      Array(
        "TEXT" => "Bitrix24",
        "LINK" => "http://bitrix24.com",
      ),
      Array(
         "TEXT" => "Echo", 
         "COMMAND" => "echo", 
         "COMMAND_PARAMS" => "test from keyboard"
      ),
      Array(
         "TEXT" => "Open app", 
         "APP_ID" => "12", 
         "APP_PARAMS" => "TEST"
      ),
   )
), $_REQUEST["auth"]);

Each custom item in the context menu is defined by a set of keys:

• TEXT - specifies text for a menu item;
• LINK - specifies a hyperlink;
• COMMAND - sends command to the bot;
• COMMAND_PARAMS - specifies command parameters;
• APP_ID - specifies ID of an installed chat application.
• APP_PARAMS - parameters that will be passed over to the chat application.
• DISABLED - specifies Y to disable the menu item.
• 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.

TEXT, LINK or COMMAND are required.

If the LINK key is not empty, the menu item is treated as an external link. If the COMMAND and COMMAND_PARAMS keys are specified, the menu item sends a command to the bot, without posting it in the chat. Available from API (platform version) revision 26

If the APP_ID and APP_PARAMS keys are specified, the menu item will open a chat application window.

If it is necessary to specify two lines with buttons in a row, then to separate them, create a button with the following content: "TYPE" => "NEWLINE".





Command Processing on the Chatbot side

Chatbots use commands to process menu items.

1. To make a command recognizable, it has to be registered using imbot.command.register method in the ONAPPINSTALL event handler. (To make the command available only from the menu, add the "HIDDEN" => "Y" key).

   Use these keys in the menu item description to fire a command:

   "COMMAND" => "page", // command to send to chatbot 
   "COMMAND_PARAMS" => "1", // command parameters
   

2. Menu item, when selected, generates ONIMCOMMANDADD event.

3. Create a new message in the event handler as a response or update an existing message (effectively creating the page navigation feature).

4. The [data][COMMAND] array passed to the event handler will contain the event information. This array now contains a new COMMAND_CONTEXT key to describe the 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 Chat

Applications for chat, launched from context menu are working based on the Context Application principles.