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

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

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

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

Чтобы добавить пункт в контекстное меню, при создании или обновлении сообщения передайте параметр 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
        
try {
            const response = await $b24.callMethod(
                'im.message.add',
                {
                    DIALOG_ID: 'chat2725',
                    MESSAGE: 'Выберите действие в меню',
                    URL_PREVIEW: 'Y',
                    MENU: {
                        ITEMS: [
                            {
                                TEXT: 'Открыть сайт',
                                LINK: 'https://www.example.ru/'
                            },
                            {
                                TEXT: 'Отправить текст',
                                ACTION: 'SEND',
                                ACTION_VALUE: 'Готово'
                            }
                        ]
                    }
                }
            );
        
            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' => 'Выберите действие в меню',
                        '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 — команда вызвана из контекстного меню
Предыдущая
Работа с клавиатурами
Следующая
Добавить сообщение