Работа с контекстным меню

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Контекстное меню — это набор действий в сообщении. Вы можете добавить свои пункты в контекстное меню, чтобы открывать ссылки или отправлять команды боту.

Методы, которые поддерживают работу с контекстным меню:

Как добавить пункт в контекстное меню

Чтобы добавить пункт в контекстное меню, при создании или обновлении сообщения передайте параметр MENU.

MENU можно передавать:

  • строкой JSON
  • объектом с корневым ключом ITEMS
  • массивом пунктов без обертки

Если в MENU нет ключа ITEMS, сервер автоматически считает, что передан сокращенный формат, и оборачивает массив в ITEMS.

{
            "MENU": {
                "ITEMS": [
                    { "TEXT": "Открыть сайт", "LINK": "https://example.com" }
                ]
            }
        }
        
{
            "MENU": [
                { "TEXT": "Открыть сайт", "LINK": "https://example.com" }
            ]
        }

Поля пункта меню

Название
тип

Описание

TEXT
string

Текст пункта меню.

Для пунктов меню обязательно указывать TEXT и одно поле действия — LINK, COMMAND, ACTION + ACTION_VALUE или APP_ID

LINK
string

Ссылка пункта меню. Допустимы http/https и относительный путь /...

COMMAND
string

Команда для бота.

Подробнее об обработке команд чат-ботом читайте ниже

COMMAND_PARAMS
string

Параметры команды. Передавайте вместе с COMMAND

APP_ID
integer

Идентификатор приложения для чата.

Устаревший сценарий. Чтобы открыть приложение из чата, используйте встройки

APP_PARAMS
string

Параметры запуска приложения для чата. Передавайте вместе с APP_ID.

Устаревший сценарий. Чтобы открыть приложение из чата, используйте встройки

На текущий момент вариант с параметрами APP_ID и APP_PARAMS используется в чатах Открытых линий

ACTION
string

Действие:

  • PUT — вставить текст в поле ввода
  • SEND — отправить текст
  • COPY — копировать текст в буфер обмена
  • CALL — позвонить
  • DIALOG — открыть чат

Доступно начиная с ревизии REST API IM 28

ACTION_VALUE
string

Значение для ACTION:

  • PUT — текст, который будет вставлен в поле ввода
  • SEND — текст, который будет отправлен
  • COPY — текст, который будет скопирован в буфер обмена
  • CALL — номер телефона в международном формате
  • DIALOG — идентификатор чата в формате chatXXX для группового чата и ID пользователя для личного чата

Доступно начиная с ревизии REST API IM 28

CONTEXT
string

Контекст отображения.

Допустимые значения:

  • MOBILE — показывать только на мобильном устройстве
  • DESKTOP — показывать только в десктопной версии
  • ALL — показывать везде

По умолчанию — ALL

DISABLED
string

Активность пункта меню.

Допустимые значения:

  • Y — пункт меню неактивен
  • N — пункт меню активен

По умолчанию — N

Пример отправки сообщения с контекстным меню

Как использовать примеры в документации

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"DIALOG_ID":"chat2725","MESSAGE":"Выберите действие в меню","URL_PREVIEW":"Y","MENU":{"ITEMS":[{"TEXT":"Открыть сайт","LINK":"https://www.example.ru/"},{"TEXT":"Отправить текст","ACTION":"SEND","ACTION_VALUE":"Готово"}]}}' \
        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":"Выберите действие в меню","URL_PREVIEW":"Y","MENU":{"ITEMS":[{"TEXT":"Открыть сайт","LINK":"https://www.example.ru/"},{"TEXT":"Отправить текст","ACTION":"SEND","ACTION_VALUE":"Готово"}]}},"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.ru/',
                  },
                  {
                    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.ru/',
                      },
                      {
                        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>
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'im.message.add',
                    [
                        'DIALOG_ID' => 'chat2725',
                        'MESSAGE' => 'Выберите действие в меню',
                        'URL_PREVIEW' => 'Y',
                        'MENU' => [
                            'ITEMS' => [
                                [
                                    'TEXT' => 'Открыть сайт',
                                    'LINK' => 'https://www.example.ru/'
                                ],
                                [
                                    'TEXT' => 'Отправить текст',
                                    'ACTION' => 'SEND',
                                    'ACTION_VALUE' => 'Готово'
                                ]
                            ]
                        ]
                    ]
                );
        
            $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: 'Выберите действие в меню',
                URL_PREVIEW: 'Y',
                MENU: {
                    ITEMS: [
                        {
                            TEXT: 'Открыть сайт',
                            LINK: 'https://www.example.ru/'
                        },
                        {
                            TEXT: 'Отправить текст',
                            ACTION: 'SEND',
                            ACTION_VALUE: 'Готово',
                        }
                    ]
                }
            },
            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' => 'Выберите действие в меню',
                'URL_PREVIEW' => 'Y',
                'MENU' => [
                    'ITEMS' => [
                        [
                            'TEXT' => 'Открыть сайт',
                            'LINK' => 'https://www.example.ru/'
                        ],
                        [
                            'TEXT' => 'Отправить текст',
                            'ACTION' => 'SEND',
                            'ACTION_VALUE' => 'Готово'
                        ]
                    ]
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Как обновить или удалить контекстное меню

Для обновления пунктов меню используйте методы:

Чтобы отключить показ дополнительных пунктов меню, передайте:

  • MENU: 'N'
  • пустое значение MENU

Обработка команд чат-ботом

  1. Чтобы команда отрабатывала в меню, зарегистрируйте ее через метод imbot.command.register.

    В пункте меню укажите следующие ключи:

    "COMMAND" => "example", // команда, которая будет отправлена чат-боту
        "COMMAND_PARAMS" => "example", // параметры для команды

  2. Нажатие на пункт меню сформирует событие ONIMCOMMANDADD.

  3. Внутри события в массиве data[COMMAND] будут переданы данные о вызванном событии. Значение COMMAND_CONTEXT покажет в каком контексте была вызвана команда:

    • TEXTAREA — команда введена вручную
    • KEYBOARD — команда вызвана кнопкой
    • MENU — команда вызвана из контекстного меню
Предыдущая
Работа с клавиатурами
Следующая
Добавить сообщение