Working with Context Menu

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to 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:

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" }
            ]
        }

Name
type

Description

TEXT
string

The text of the menu item.

For menu items, it is mandatory to specify TEXT and one action field — LINK, COMMAND, ACTION + ACTION_VALUE, or APP_ID

LINK
string

The link for the menu item. http/https and relative paths /... are allowed.

COMMAND
string

The command for the bot.

For more details on command processing by the chat bot, see below

COMMAND_PARAMS
string

Command parameters. Pass together with COMMAND

APP_ID
integer

The application identifier for the chat.

Deprecated scenario. To open an application from chat, use widgets.

APP_PARAMS
string

Parameters for launching the application in chat. Pass together with APP_ID.

Deprecated scenario. To open an application from chat, use widgets.

Currently, the option with parameters APP_ID and APP_PARAMS is used in chats Open Channels

ACTION
string

Action:

  • PUT — insert text into the input field
  • SEND — send text
  • COPY — copy text to clipboard
  • CALL — make a call
  • DIALOG — open chat

Available starting from REST API IM revision 28

ACTION_VALUE
string

Value for ACTION:

  • PUT — text to be inserted into the input field
  • SEND — text to be sent
  • COPY — text to be copied to clipboard
  • CALL — phone number in international format
  • DIALOG — chat identifier in the format chatXXX for group chat and ID of the user for personal chat

Available starting from REST API IM revision 28

CONTEXT
string

Display context.

Allowed values:

  • MOBILE — show only on mobile devices
  • DESKTOP — show only in desktop version
  • ALL — show everywhere

Default is ALL

DISABLED
string

Activity of the menu item.

Allowed values:

  • Y — menu item is inactive
  • N — menu item is active

Default is N

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
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        try {
          const response = await $b24.actions.v2.call.make<number>({
            method: 'im.message.add',
            params: {
              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',
                  },
                ],
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Created message with ID:', result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function addMessageWithMenu() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'im.message.add',
                params: {
                  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',
                      },
                    ],
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Created message with ID:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', addMessageWithMenu)
        </script>
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.im.message.add(
                dialog_id="chat2725",
                message="Select an action from the menu",
                url_preview=True,
                menu={
                    "ITEMS": [
                        {
                            "TEXT": "Open the website",
                            "LINK": "https://www.example.com/",
                        },
                        {
                            "TEXT": "Send the text",
                            "ACTION": "SEND",
                            "ACTION_VALUE": "Done",
                        },
                    ],
                },
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected 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>';
        
// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "im.message.add", b24.Params{
        	"DIALOG_ID":   "chat2725",
        	"MESSAGE":     "Select an action from the menu",
        	"URL_PREVIEW": "Y",
        	"MENU": b24.Params{
        		"ITEMS": []b24.Params{
        			{
        				"TEXT": "Open Website",
        				"LINK": "https://www.example.com/",
        			},
        			{
        				"TEXT":         "Send Text",
        				"ACTION":       "SEND",
        				"ACTION_VALUE": "Done",
        			},
        		},
        	},
        })
        if err != nil {
        	return fmt.Errorf("im.message.add: %w", err)
        }
        
        // The response arrives as json.RawMessage — unmarshal it
        // into a struct matching the response shape shown below on this page.
        fmt.Printf("%s\n", res.Result)

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

  1. 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

  2. Clicking on the menu item will generate the event ONIMCOMMANDADD.

  3. Inside the event, the array data[COMMAND] will contain data about the invoked event. The value COMMAND_CONTEXT will indicate the context in which the command was invoked:

    • TEXTAREA — command entered manually
    • KEYBOARD — command invoked by button
    • MENU — command invoked from the context menu

Continue Learning

Previous
Working with Keyboards
Next
Add Message