Working with Keyboards

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 keyboard consists of buttons beneath a message. They can open links, perform actions, and trigger commands. Use a keyboard when an action should remain a separate button beneath the message; for an action within the text, use BBCode.

Methods that support keyboard functionality:

Chatbots 2.0 (imbot.v2)

Chats (im)

How to Add a Keyboard

To add a keyboard when creating or updating a message, pass it in fields.keyboard for imbot.v2 methods or as the top-level KEYBOARD parameter for im.* methods. imbot.v2 calls require the imbot scope and access as the registered bot's owner. When authorizing with a webhook, pass botToken as a method parameter. Access requirements for im.* methods are described on their pages.

A keyboard or KEYBOARD value can be passed as:

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

If the keyboard value does not contain the BUTTONS key, the server treats it as a shortened format and wraps the array in BUTTONS. Button field names inside BUTTONS are uppercase in both API versions.

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

In the examples above, KEYBOARD is shown as a parameter of im.* methods. For imbot.v2 methods, pass its contents in fields.keyboard, as shown in the message sending examples below.

How to Choose an Action

If You Need To

Use

What Happens

Show a separate button that performs an action in the chat interface

ACTION with ACTION_VALUE in the button

The client inserts or sends text, copies it, starts a call, or opens a dialog. An ACTION button does not generate a separate click event

Receive a button click event and handle it in the bot

COMMAND in the button

The registered command triggers ONIMBOTV2COMMANDADD with command.context: "keyboard"

Send a command directly from the message text without a separate button

[send=] BBCode

Clicking the link in the text sends the command immediately

A button with ACTION: "SEND" sends the text from ACTION_VALUE. To make the bot react to a specific button, register a command and specify it in COMMAND.

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

BLOCK works only for buttons with COMMAND:

  • COMMAND + BLOCK=Y — the button is blocked after it is pressed
  • ACTION + BLOCK=Y — the button performs the action but is not blocked

Buttons with ACTION are executed on the client side. The bot does not control them and cannot unblock them.

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 action","keyboard":{"BOT_ID":456,"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":{"BOT_ID":456,"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: {
                        BOT_ID: 456,
                        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);
        }
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.imbot.v2.chat.message.send(
                bot_id=456,
                dialog_id="chat2725",
                fields={
                    "message": "Select an action",
                    "keyboard": {
                        "BOT_ID": 456,
                        "BUTTONS": [
                            {
                                "TEXT": "Open the website",
                                "LINK": "https://www.example.com/",
                            },
                            {
                                "TYPE": "NEWLINE",
                            },
                            {
                                "TEXT": "Insert the command",
                                "ACTION": "PUT",
                                "ACTION_VALUE": "/help",
                            },
                        ],
                    },
                },
            ).response
            result = bitrix_response.result["id"]
            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(
                    'imbot.v2.Chat.Message.send',
                    [
                        'botId' => 456,
                        'dialogId' => 'chat2725',
                        'fields' => [
                            'message' => 'Select an action',
                            'keyboard' => [
                                'BOT_ID' => 456,
                                '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: {
                        BOT_ID: 456,
                        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' => [
                        'BOT_ID' => 456,
                        '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 delete a keyboard

To update buttons, use the following methods:

When updating a keyboard, specify BOT_ID inside the keyboard object, at the same level as BUTTONS. If you pass only BUTTONS, the button command may not be routed to the correct bot.

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

Continue Learning

Previous
Text Formatting
Next
How to Use Attachments