Working with Context Menu
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.
The context menu is a set of actions within a message. You can add your own items to the context menu to open links or send commands to the bot.
Methods that support context menu functionality:
- imbot.message.add — send a message on behalf of the chat bot
- imbot.message.update — modify a sent message from the chat bot
- imbot.command.answer — send a response to a command from the chat bot
- im.message.add — send a message in chat
- im.message.update — modify a sent message
How to Add an Item to the Context Menu
To add an item to the context menu, pass the MENU parameter when creating or updating a message.
MENU can be passed as:
- a JSON string
- an object with the root key
ITEMS - an array of items without wrapping
If the MENU does not contain the key ITEMS, the server will automatically assume that a shortened format has been provided and will wrap the array in ITEMS.
{
"MENU": {
"ITEMS": [
{ "TEXT": "Open Website", "LINK": "https://example.com" }
]
}
}
{
"MENU": [
{ "TEXT": "Open Website", "LINK": "https://example.com" }
]
}
Menu Item Fields
|
Name |
Description |
|
TEXT |
The text of the menu item. For menu items, it is mandatory to specify |
|
LINK |
The link for the menu item. |
|
COMMAND |
The command for the bot. For more details on command processing by the chat bot, see below |
|
COMMAND_PARAMS |
Command parameters. Pass together with |
|
APP_ID |
The application identifier for the chat. Deprecated scenario. To open an application from chat, use widgets. |
|
APP_PARAMS |
Parameters for launching the application in chat. Pass together with Deprecated scenario. To open an application from chat, use widgets. Currently, the option with parameters |
|
ACTION |
Action:
Available starting from REST API IM revision 28 |
|
ACTION_VALUE |
Value for
Available starting from REST API IM revision 28 |
|
CONTEXT |
Display context. Allowed values:
Default is |
|
DISABLED |
Activity of the menu item. Allowed values:
Default is |
Example of Sending a Message with a Context Menu
How to Use Examples in Documentation
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"DIALOG_ID":"chat2725","MESSAGE":"Select an action from the menu","URL_PREVIEW":"Y","MENU":{"ITEMS":[{"TEXT":"Open Website","LINK":"https://www.example.com/"},{"TEXT":"Send Text","ACTION":"SEND","ACTION_VALUE":"Done"}]}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/im.message.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"DIALOG_ID":"chat2725","MESSAGE":"Select an action from the menu","URL_PREVIEW":"Y","MENU":{"ITEMS":[{"TEXT":"Open Website","LINK":"https://www.example.com/"},{"TEXT":"Send Text","ACTION":"SEND","ACTION_VALUE":"Done"}]}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/im.message.add
try {
const response = await $b24.callMethod(
'im.message.add',
{
DIALOG_ID: 'chat2725',
MESSAGE: 'Select an action from the menu',
URL_PREVIEW: 'Y',
MENU: {
ITEMS: [
{
TEXT: 'Open Website',
LINK: 'https://www.example.com/'
},
{
TEXT: 'Send Text',
ACTION: 'SEND',
ACTION_VALUE: 'Done'
}
]
}
}
);
const result = response.getData().result;
console.log('Created message with ID:', result);
processResult(result);
} catch (error) {
console.error('Error:', error);
}
try {
$response = $b24Service
->core
->call(
'im.message.add',
[
'DIALOG_ID' => 'chat2725',
'MESSAGE' => 'Select an action from the menu',
'URL_PREVIEW' => 'Y',
'MENU' => [
'ITEMS' => [
[
'TEXT' => 'Open Website',
'LINK' => 'https://www.example.com/'
],
[
'TEXT' => 'Send Text',
'ACTION' => 'SEND',
'ACTION_VALUE' => 'Done'
]
]
]
]
);
$result = $response
->getResponseData()
->getResult();
echo 'Success: ' . print_r($result, true);
processData($result);
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error adding message: ' . $e->getMessage();
}
BX24.callMethod(
'im.message.add',
{
DIALOG_ID: 'chat2725',
MESSAGE: 'Select an action from the menu',
URL_PREVIEW: 'Y',
MENU: {
ITEMS: [
{
TEXT: 'Open Website',
LINK: 'https://www.example.com/'
},
{
TEXT: 'Send Text',
ACTION: 'SEND',
ACTION_VALUE: 'Done',
}
]
}
},
function(result) {
if (result.error()) {
console.error(result.error().ex);
} else {
console.log(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'im.message.add',
[
'DIALOG_ID' => 'chat2725',
'MESSAGE' => 'Select an action from the menu',
'URL_PREVIEW' => 'Y',
'MENU' => [
'ITEMS' => [
[
'TEXT' => 'Open Website',
'LINK' => 'https://www.example.com/'
],
[
'TEXT' => 'Send Text',
'ACTION' => 'SEND',
'ACTION_VALUE' => 'Done'
]
]
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
How to Update or Remove the Context Menu
To update menu items, use the methods:
To disable the display of additional menu items, pass:
MENU: 'N'- an empty value for
MENU
Command Processing by the Chat Bot
-
To ensure the command works in the menu, register it using the method imbot.command.register.
In the menu item, specify the following keys:
"COMMAND" => "example", // command that will be sent to the chat bot "COMMAND_PARAMS" => "example", // parameters for the command -
Clicking on the menu item will generate the event ONIMCOMMANDADD.
-
Inside the event, the array
data[COMMAND]will contain data about the invoked event. The valueCOMMAND_CONTEXTwill indicate the context in which the command was invoked:TEXTAREA— command entered manuallyKEYBOARD— command invoked by buttonMENU— command invoked from the context menu