Working with Keyboards

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 keyboard consists of buttons beneath the message. They can be used to open links, perform actions, and trigger commands.

Methods that support keyboard functionality:

Chatbots 2.0 (imbot.v2)

Chats (im)

Deprecated Chatbots (imbot)

How to Add a Keyboard

To add a keyboard, pass the KEYBOARD parameter when creating or updating a message.

KEYBOARD can be passed as:

  • a JSON string
  • an object with the root key BUTTONS
  • an array of buttons without wrapping

If the KEYBOARD does not contain the BUTTONS key, the server will automatically assume that a shortened format has been provided and will wrap the array in BUTTONS.

{
            "KEYBOARD": {
                "BUTTONS": [
                    {"TEXT": "Button", "LINK": "https://example.com"}
                ]
            }
        }
        
{
            "KEYBOARD": [
                {"TEXT": "Button", "LINK": "https://example.com"}
            ]
        }

Button Fields

Name
type

Description

TEXT
string

Button text.

For all buttons except TYPE, it is mandatory to specify TEXT and one action field: LINK, COMMAND, ACTION + ACTION_VALUE, or APP_ID

TYPE
string

Move the button to a new line. The only allowed value is NEWLINE

LINK
string

Button link. http/https and relative path /... are allowed

APP_ID
integer

Application identifier for the chat.

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

APP_PARAMS
string

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

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

ACTION
string

Action:

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

ACTION_VALUE
string

Value for ACTION:

  • PUT — text to insert into the input field
  • SEND — text to send
  • COPY — text to copy
  • CALL — phone number in international format
  • DIALOG — chat identifier (chatXXX) or ID of the user for a personal chat

COMMAND
string

Command for the bot. More about processing — below

COMMAND_PARAMS
string

Command parameters. Pass together with COMMAND

BLOCK
string

Button blocking:

  • Y — block after pressing
  • N — do not block

Default is N

DISABLED
string

Button activity:

  • Y — button is inactive
  • N — button is active

Default is N

CONTEXT
string

Display context:

  • MOBILE — mobile device only
  • DESKTOP — desktop only
  • ALL — everywhere

Default is ALL

DISPLAY
string

Button display:

  • LINE — button in line
  • BLOCK — button as a separate block

Default is BLOCK

WIDTH
integer

Button width in pixels

BG_COLOR
string

Button color in HEX format

BG_COLOR_TOKEN
string

Button color token:

  • primary
  • secondary
  • alert
  • base

Default is base

TEXT_COLOR
string

Button text color in HEX format

OFF_BG_COLOR
string

Button color in inactive state

OFF_TEXT_COLOR
string

Button text color in inactive state

The option with APP_ID and APP_PARAMS parameters is used in chats of Open Channels.

Example of Sending a Message with a Keyboard

How to Use Examples in Documentation

curl -X POST \
          -H "Content-Type: application/json" \
          -H "Accept: application/json" \
          -d '{"botId":456,"botToken":"my_bot_token","dialogId":"chat2725","fields":{"message":"Select an action","keyboard":{"BUTTONS":[{"TEXT":"Open website","LINK":"https://www.example.com/"},{"TYPE":"NEWLINE"},{"TEXT":"Insert command","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":"Select an action","keyboard":{"BUTTONS":[{"TEXT":"Open website","LINK":"https://www.example.com/"},{"TYPE":"NEWLINE"},{"TEXT":"Insert command","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: 'Select an action',
                    keyboard: {
                        BUTTONS: [
                            { TEXT: 'Open website', LINK: 'https://www.example.com/' },
                            { TYPE: 'NEWLINE' },
                            { TEXT: 'Insert command', 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' => 'Select an action',
                            'keyboard' => [
                                'BUTTONS' => [
                                    ['TEXT' => 'Open website', 'LINK' => 'https://www.example.com/'],
                                    ['TYPE' => 'NEWLINE'],
                                    ['TEXT' => 'Insert command', '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: 'Select an action',
                    keyboard: {
                        BUTTONS: [
                            { TEXT: 'Open website', LINK: 'https://www.example.com/' },
                            { TYPE: 'NEWLINE' },
                            { TEXT: 'Insert command', 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' => 'Select an action',
                    'keyboard' => [
                        'BUTTONS' => [
                            ['TEXT' => 'Open website', 'LINK' => 'https://www.example.com/'],
                            ['TYPE' => 'NEWLINE'],
                            ['TEXT' => 'Insert command', 'ACTION' => 'PUT', 'ACTION_VALUE' => '/help'],
                        ],
                    ],
                ],
            ]
        );
        
        if (!empty($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo 'Message ID: ' . $result['result']['id'];
        }

How to Update or Remove a Keyboard

To update buttons, use the following methods:

To disable button display, pass:

  • KEYBOARD: 'N'
  • an empty value for KEYBOARD

Command Processing by the Chatbot

  1. To ensure the command works with the keyboard, register it using the method imbot.v2.Command.register.

  2. Pressing a button will generate the event ONIMBOTV2COMMANDADD.

  3. In the event, the value of command.context indicates the context in which the command was invoked:

  • textarea — entered manually
  • keyboard — invoked by a button
  • menu — invoked from the context menu
Previous
Text Formatting
Next
How to Use Attachments