Работа с клавиатурами

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

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

Чат-боты 2.0 (imbot.v2)

Чаты (im)

Устаревшие чат-боты (imbot)

  • imbot.message.add — отправить сообщение от имени чат-бота
  • imbot.message.update — изменить отправленное сообщение чат-бота
  • imbot.command.answer — отправить ответ на команду чат-бота

Как добавить клавиатуру

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

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

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

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

{
            "KEYBOARD": {
                "BUTTONS": [
                    {"TEXT": "Кнопка", "LINK": "https://example.ru"}
                ]
            }
        }
        
{
            "KEYBOARD": [
                {"TEXT": "Кнопка", "LINK": "https://example.ru"}
            ]
        }

Поля кнопки

Название
тип

Описание

TEXT
string

Текст кнопки.

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

TYPE
string

Перенос кнопки на новую строку. Единственное допустимое значение — NEWLINE

LINK
string

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

APP_ID
integer

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

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

APP_PARAMS
string

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

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

ACTION
string

Действие:

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

ACTION_VALUE
string

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

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

COMMAND
string

Команда для бота. Подробнее об обработке — ниже

COMMAND_PARAMS
string

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

BLOCK
string

Блокировка кнопки:

  • Y — блокировать после нажатия
  • N — не блокировать

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

DISABLED
string

Активность кнопки:

  • Y — кнопка неактивна
  • N — кнопка активна

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

CONTEXT
string

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

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

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

DISPLAY
string

Отображение кнопки:

  • LINE — кнопка в строке
  • BLOCK — кнопка отдельным блоком

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

WIDTH
integer

Ширина кнопки в пикселях

BG_COLOR
string

Цвет кнопки в формате HEX

BG_COLOR_TOKEN
string

Токен цвета кнопки:

  • primary
  • secondary
  • alert
  • base

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

TEXT_COLOR
string

Цвет текста кнопки в формате HEX

OFF_BG_COLOR
string

Цвет кнопки в неактивном состоянии

OFF_TEXT_COLOR
string

Цвет текста кнопки в неактивном состоянии

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

Пример отправки сообщения с клавиатурой

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

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"botToken":"my_bot_token","dialogId":"chat2725","fields":{"message":"Выберите действие","keyboard":{"BUTTONS":[{"TEXT":"Открыть сайт","LINK":"https://www.example.ru/"},{"TYPE":"NEWLINE"},{"TEXT":"Подставить команду","ACTION":"PUT","ACTION_VALUE":"/help"}]}}}' \
          https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Chat.Message.send
        
curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"dialogId":"chat2725","fields":{"message":"Выберите действие","keyboard":{"BUTTONS":[{"TEXT":"Открыть сайт","LINK":"https://www.example.ru/"},{"TYPE":"NEWLINE"},{"TEXT":"Подставить команду","ACTION":"PUT","ACTION_VALUE":"/help"}]}},"auth":"**put_access_token_here**"}' \
          https://**put_your_bitrix24_address**/rest/imbot.v2.Chat.Message.send
        
try {
            const response = await $b24.callMethod('imbot.v2.Chat.Message.send', {
                botId: 456,
                dialogId: 'chat2725',
                fields: {
                    message: 'Выберите действие',
                    keyboard: {
                        BUTTONS: [
                            { TEXT: 'Открыть сайт', LINK: 'https://www.example.ru/' },
                            { TYPE: 'NEWLINE' },
                            { TEXT: 'Подставить команду', ACTION: 'PUT', ACTION_VALUE: '/help' },
                        ],
                    },
                },
            });
        
            const result = response.getData().result.id;
            console.log('Created message ID:', result);
        } catch (error) {
            console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'imbot.v2.Chat.Message.send',
                    [
                        'botId' => 456,
                        'dialogId' => 'chat2725',
                        'fields' => [
                            'message' => 'Выберите действие',
                            'keyboard' => [
                                'BUTTONS' => [
                                    ['TEXT' => 'Открыть сайт', 'LINK' => 'https://www.example.ru/'],
                                    ['TYPE' => 'NEWLINE'],
                                    ['TEXT' => 'Подставить команду', 'ACTION' => 'PUT', 'ACTION_VALUE' => '/help'],
                                ],
                            ],
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult()['id'];
        
            echo 'Created message ID: ' . $result;
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'imbot.v2.Chat.Message.send',
            {
                botId: 456,
                dialogId: 'chat2725',
                fields: {
                    message: 'Выберите действие',
                    keyboard: {
                        BUTTONS: [
                            { TEXT: 'Открыть сайт', LINK: 'https://www.example.ru/' },
                            { TYPE: 'NEWLINE' },
                            { TEXT: 'Подставить команду', ACTION: 'PUT', ACTION_VALUE: '/help' },
                        ],
                    },
                },
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error().ex);
                } else {
                    console.log('Message ID:', result.data().id);
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'imbot.v2.Chat.Message.send',
            [
                'botId' => 456,
                'dialogId' => 'chat2725',
                'fields' => [
                    'message' => 'Выберите действие',
                    'keyboard' => [
                        'BUTTONS' => [
                            ['TEXT' => 'Открыть сайт', 'LINK' => 'https://www.example.ru/'],
                            ['TYPE' => 'NEWLINE'],
                            ['TEXT' => 'Подставить команду', 'ACTION' => 'PUT', 'ACTION_VALUE' => '/help'],
                        ],
                    ],
                ],
            ]
        );
        
        if (!empty($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo 'Message ID: ' . $result['result']['id'];
        }

Как обновить или удалить клавиатуру

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

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

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

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

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

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

  3. В событии значение command.context показывает, в каком контексте была вызвана команда:

  • textarea — введена вручную
  • keyboard — вызвана кнопкой
  • menu — вызвана из контекстного меню
Предыдущая
Форматирование текста
Следующая
Как использовать вложения