Views: 8068
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.
- 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
Menu item, when selected, generates ONIMCOMMANDADD event.
Create a new message in the event handler as a response or update an existing message (effectively creating the page navigation feature).
- 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.