Views: 1176 (Data available since 06.02.2017)

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


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:

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"]);

Note: The example uses the restCommand function. It is used here for illustration only. You can send a REST command with your own function, or use BX24.callMethod or bitrix24-php-sdk methods.

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.

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.

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.




Courses developed by «Bitrix», Inc.