Views: 7881
Last Modified: 23.03.2022

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: restCommand function is used here for illustration purposes only. It is taken from the EchoBot example; it is used. You can send a REST command with your own function, or use the 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.
  • 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.




Courses developed by Bitrix24