Кнопки

Труконф02.10.2026Около 13 мин

Кнопки

С версии 5.5.6 TrueConf Chatbot Connector поддерживает inline-кнопки, которые отображаются непосредственно под сообщением:

Inline-кнопки позволяют пользователю взаимодействовать с ботом без ввода текста: выполнить команду, открыть ссылку, отправить сообщение или скопировать данные в буфер обмена. Кнопки прикрепляются к сообщениям с типом 200 (PLAIN_MESSAGE) и могут отправляться только чат-ботами. Изменение набора кнопок отправленного сообщения выполняется через его редактирование (editMessage).

Отображение inline-кнопок в чате зависит от версии клиентского приложения:

Windows/Linux/macOS: 8.6.0+
Android: 3.3.0+
iOS: 4.2.0+

Стили кнопок

Для кнопок доступны разные стили оформления:

Стиль можно задать с помощью необязательного поля style. Если поле не указано, используется стиль по умолчанию.

Стиль	Значение `style`	Описание
По умолчанию	не указывается	Стандартное оформление кнопки, используется, если поле `style` не задано
Акцентный	`primary`	Кнопка выделяется акцентным цветом клиентского приложения
Опасный	`danger`	Стиль для «опасных» действий
Позитивный	`success`	Стиль для «позитивных» действий

Типы кнопок

На данный момент поддерживается четыре типа кнопок. Тип задаётся с помощью обязательного поля type внутри объекта кнопки.

Тип	Значение `type`	Назначение
Сообщение	`message`	Отправляет сообщение в чат от имени пользователя или вставляет его как черновик
Ссылка	`url`	Открывает внешнюю ссылку или ресурс TrueConf
Копирование	`copy`	Копирует данные в буфер обмена
Команда	`command`	Отправляет команду боту без публикации сообщения в чат

Кнопка «message»

Кнопка отправляет в чат сообщение, сформированное ботом, от имени пользователя, нажавшего кнопку. Если указан параметр draft: true, сообщение не отправляется, а помещается в поле ввода текста клиентского приложения как черновик.

Поле	Тип	Обяз.	Описание
type	string	Да	Тип кнопки — строка `"message"`
id	string	Нет	Уникальный идентификатор кнопки, строка. Может использоваться для дополнительной идентификации нажатой кнопки
label	string	Да	Строка, которая будет отображена на кнопке в клиенте, максимальная длина — 32 символа Unicode
style	string	Нет	Способ отображения кнопки: `primary`, `danger`, `success`
message	string	Да	Текст сообщения, которое будет отправлено при нажатии. Применяются все правила и ограничения, как и к тексту стандартных отправляемых сообщений
draft	boolean	Нет	Если `true`, вместо отправки сообщение помещается в поле ввода текста клиента как черновик. Если в поле до этого был другой черновик, он перетирается

Пример кнопки:

{
    "type": "message",
    "label": "Написать приветствие",
    "message": "Привет, коллеги!",
    "draft": false
}

Кнопка «url»

Кнопка открывает ссылку. Поддерживаются протоколы http://, https://, mailto: и trueconf:. Если надпись кнопки не задана, на кнопке отображается значение ссылки.

Поле	Тип	Обяз.	Описание
type	string	Да	Тип кнопки — строка `"url"`
id	string	Нет	Уникальный идентификатор кнопки, строка. Может использоваться для дополнительной идентификации нажатой кнопки
label	string	Нет	Строка, которая будет отображена на кнопке в клиенте, максимальная длина — 32 символа Unicode. Если не передана, название будет взято из ссылки
style	string	Нет	Способ отображения кнопки: `primary`, `danger`, `success`
url	string	Да	Ссылка на ресурс, который необходимо открыть. Строка длиной от 8 до 8095 символов ASCII. Поддерживаются только протоколы `http://`, `https://`, `mailto:`, `trueconf:`

Поведение кнопки зависит от протокола ссылки:

http:// и https:// — ссылка открывается во внешнем браузере, кнопка имеет визуальный маркер «внешняя ссылка»;
mailto: — по умолчанию открывается внешний почтовый клиент, кнопка имеет визуальный маркер «email»;
trueconf: — открывается ресурс TrueConf:
- TrueConf ID пользователя в формате trueconf:user@server.name с опциональным параметром do;
- ID конференции в формате trueconf:\c\cid@server.name#vcs;
- допускаются любые опциональные параметры, но клиент принудительно всегда доклеивает (или переопределяет, если они были переданы) следующие параметры: &templogin=1, &autoclose=0, &force=0.

Если для кнопки не задана надпись (label), на кнопке отображается её значение. Если значение — это TrueConf ID пользователя без параметров в формате user@server.name, отображается сетевой статус и отображаемое имя (display name) пользователя из адресной книги клиента. Если в адресной книге нет такого TrueConf ID, вместо отображаемого имени выводится полный TrueConf ID вида john_doe@video.example.com.

Пример кнопки:

{
    "type": "url",
    "label": "Открыть сайт",
    "url": "https://trueconf.com",
    "style": "primary"
}

Кнопка «copy»

Кнопка копирует в буфер обмена текст, сформированный ботом. При нажатии в клиентском приложении кратковременно выводится локализованная нотификация о том, что данные скопированы в буфер обмена. Кнопка имеет визуальный маркер «copy».

Поле	Тип	Обяз.	Описание
type	string	Да	Тип кнопки — строка `"copy"`
id	string	Нет	Уникальный идентификатор кнопки, строка. Может использоваться для дополнительной идентификации нажатой кнопки
label	string	Да	Строка, которая будет отображена на кнопке в клиенте, максимальная длина — 32 символа Unicode
style	string	Нет	Способ отображения кнопки: `primary`, `danger`, `success`
data	string	Да	Текст, который будет помещен в буфер обмена. Строка от 1 до 4095 символов Unicode

Пример кнопки:

{
    "type": "copy",
    "label": "Скопировать промокод",
    "data": "ПРОМОКОД-12345",
    "style": "danger"
}

Кнопка «command»

Кнопка отправляет команду подключенному боту без публикации сообщения в чат. При нажатии кнопки подключенному боту приходит уведомление с методом command — см. раздел «Уведомление о нажатии». Если у кнопки задано waitReply: true, бот должен ответить на команду с помощью запроса answerCommand.

Поле	Тип	Обяз.	Описание
type	string	Да	Тип кнопки — строка `"command"`
id	string	Нет	Уникальный идентификатор кнопки, строка. Может использоваться для дополнительной идентификации нажатой кнопки
label	string	Да	Строка, которая будет отображена на кнопке в клиенте, максимальная длина — 32 символа Unicode
style	string	Нет	Способ отображения кнопки: `primary`, `danger`, `success`
waitReply	boolean	Нет	Ожидается ли дополнительный ответ после обработки команды ботом. Если `true`, в уведомлении о нажатии будет присутствовать `commandId`, на который бот должен ответить
command	string	Да	Строка с командой для бота, от 1 до 255 ASCII-символов
customData	string	Нет	Строка с дополнительной информацией о команде, от 1 до 4096 ASCII-символов. Может содержать, например, JSON-объект
to	string	Нет	TrueConf ID другого бота, которому эта команда должна быть перенаправлена

Пример кнопки:

{
    "type": "command",
    "id": "button_98",
    "label": "Добавить товар в корзину",
    "command": "add_to_cart",
    "waitReply": true,
    "customData": "eyBwcm9kdWN0SWQgOiAiMHIyZmozamY5ajM5MyIgfQ=="
}

Ограничения

При использовании кнопок учитывайте следующие ограничения:

Под сообщением можно разместить до 64 кнопок: не более 8 рядов по 8 кнопок в каждом.
Иконки могут скрываться в зависимости от количества кнопок в ряду. Например, в клиентском приложении TrueConf для Windows, macOS, Linux они не отображаются, если ряд содержит более 4 кнопок.
Текст кнопки отображается в одну строку. Если текст не помещается в доступную область, его часть скрывается за многоточием.
Значение поля label не должно превышать 32 символа Unicode. Допускаются любые Unicode-символы, включая эмодзи.
HTML- и Markdown-разметка в тексте кнопки не обрабатывается и отображается как обычный текст.
Символы переноса строки (\n) заменяются пробелами.
Некорректно заданная кнопка не отображается.
Кнопки можно прикреплять только к сообщениям типа 200 (PLAIN_MESSAGE). Отправлять сообщения с кнопками могут только чат-боты.
Для изменения набора кнопок, например при реализации навигации, отредактируйте сообщение с помощью метода editMessage.

Как отправить кнопки

Кнопки передаются в поле buttons объекта content запроса sendMessage. Кнопки объединяются в ряды: каждый ряд задаётся отдельным массивом объектов кнопок:

buttons
├── [ ... ]  ← первый ряд
│   ├── { ... } ← кнопка
│   ├── { ... } ← кнопка
│   └── { ... } ← кнопка
└── [ ... ]  ← второй ряд
    ├── { ... } ← кнопка
    └── { ... } ← кнопка

Ряды и расположенные в них кнопки отображаются в клиентском приложении в том же порядке, в котором они указаны в buttons. Под сообщением можно разместить не более 8 рядов по 8 кнопок в каждом — всего до 64 кнопок (см. ограничения).

Запрос:

{
    "method": "sendMessage",
    "id": 7,
    "type": 1,
    "payload": {
        "chatId": "187f82e38567242a0ff266e022ffe2fc5ad24e1e",
        "content": {
            "text": "Привет, коллега! Я бот с кнопками. Нажми на любую кнопку, чтобы увидеть как это работает:",
            "parseMode": "text",
            "buttons": [
                [
                    {
                        "type": "command",
                        "to": "bot1@server.trueconf.name",
                        "label": "Отправь команду!",
                        "command": "my_awesome_command",
                        "waitReply": false
                    },
                    {
                        "type": "command",
                        "id": "button_98",
                        "label": "🛒 Добавить товар",
                        "command": "add_to_cart",
                        "waitReply": true,
                        "customData": "eyBwcm9kdWN0SWQgOiAiMHIyZmozamY5ajM5MyIgfQ=="
                    },
                    {
                        "type": "url",
                        "label": "Открыть сайт",
                        "url": "https://trueconf.com",
                        "style": "primary"
                    }
                ],
                [
                    {
                        "type": "copy",
                        "label": "Скопировать промокод",
                        "data": "PROMO-12345",
                        "style": "danger"
                    },
                    {
                        "type": "message",
                        "label": "Написать приветствие",
                        "message": "Привет, коллеги!",
                        "draft": false
                    }
                ]
            ]
        }
    }
}

В этом примере под сообщением отображаются два ряда кнопок.

Первый ряд содержит три кнопки: «Отправь команду боту 1!», «Добавить товар в корзину» и «Открыть сайт».
Второй ряд содержит две кнопки: «Скопировать промокод» и «Написать приветствие».

Пример объекта Envelope с кнопками вы найдёте в разделе «Примеры Envelope».

Ответ на запрос — стандартный ответ sendMessage.

В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.

Уведомление о нажатии

При нажатии пользователем кнопки с типом command подключенному боту приходит уведомление с методом command:

Уведомление:

{
    "method": "command",
    "id": 12,
    "type": 1,
    "payload": {
        "commandId": "89cbb2d1-e173-4833-87d1-8da7d98fda34",
        "commandSource": {
            "type": "inlineKeyboard",
            "message": {
                "chat": {
                    "chatId": "187f82e38567242a0ff266e022ffe2fc5ad24e1e",
                    "chatTitle": "Переписка",
                    "chatType": 2
                },
                "chatId": "187f82e38567242a0ff266e022ffe2fc5ad24e1e",
                "messageId": "d89e4aa7-767c-4962-9e08-35beb0a5f6cc",
                "timestamp": 1788360190573,
                "author": {
                    "id": "buttons_bot@server.trueconf.name",
                    "type": 1
                },
                "box": {
                    "id": 17,
                    "position": "0"
                },
                "type": 200,
                "content": {
                    "text": "текст сообщения",
                    "parseMode": "html"
                },
                "isEdited": false
            }
        },
        "commandPayload": {
            "type": "userCommand",
            "command": "add_to_cart",
            "customData": "eyBwcm9kdWN0SWQgOiAiMHIyZmozamY5ajM5MyIgfQ=="
        }
    }
}

Поле	Тип	Обяз.	Описание
method	string	Да	Метод `command`
id	uint32	Да	Идентификатор уведомления
type	uint32	Да	Тип сообщения (по умолчанию `1`). Соответствует MESSAGE_TYPE.REQUEST
commandId	string	Нет	Уникальный идентификатор команды. Присутствует, если у кнопки свойство `waitReply` со значением `true`. Используется для отправки ответа на команду — см. ниже
commandSource	object	Да	Источник команды
commandSource.type	string	Да	Тип источника. Строка `"inlineKeyboard"` обозначает, что команда пришла от кнопки в сообщении
commandSource.message	object	Нет	Присутствует, если `commandSource.type = "inlineKeyboard"`. Содержит объект сообщения (формат Envelope), к которому была прикреплена нажатая кнопка
commandPayload	object	Да	Данные команды
commandPayload.type	string	Да	Тип данных команды. Строка `"userCommand"` означает, что команда была отправлена с кнопки с типом `command`
commandPayload.command	string	Нет	Присутствует, если `commandPayload.type = "userCommand"`. Содержит строку из поля `command` объекта кнопки
commandPayload.customData	string	Нет	Присутствует, если `commandPayload.type = "userCommand"`. Содержит строку из поля `customData` объекта кнопки

Как и на любое другое уведомление сервера, на него необходимо ответить подтверждением (см. ответ клиента на запрос сервера):

{
    "type": 2,
    "id": 123456
}

Если поле commandId во входящем уведомлении отсутствует, команда не ожидает дополнительного ответа.

Ответ на команду

Если в уведомлении command присутствует поле commandId, боту необходимо ответить на команду. Для этого отправляется запрос с методом answerCommand:

Запрос:

{
    "method": "answerCommand",
    "id": 13,
    "type": 1,
    "payload": {
        "commandId": "89cbb2d1-e173-4833-87d1-8da7d98fda34",
        "answerType": "complete",
        "message": {
            "status": "ok",
            "visibility": "alert",
            "level": "info",
            "text": "Hakuna Matata!"
        }
    }
}

Поле	Тип	Обяз.	Описание
method	string	Да	Метод `answerCommand`
id	uint32	Да	Уникальный идентификатор запроса
type	uint32	Да	Тип сообщения (по умолчанию `1`). Соответствует MESSAGE_TYPE.REQUEST
commandId	string	Да	Уникальный идентификатор команды, равен соответствующей строке из входящего уведомления
answerType	string	Да	Тип ответа на команду. Может принимать одно из значений: `complete`, `timeout`, `cancel`, `message`
message	object	Нет	Дополнительное сообщение для пользователя
message.status	string	Нет	Статус ответа. Может принимать одно из значений: `unknown`, `pending`, `running`, `ok`, `failed`, `canceled`, `timeout`
message.visibility	string	Нет	Способ отображения ответа. Может принимать одно из значений: `default`, `toast`, `sticky`, `alert`
message.level	string	Нет	Уровень важности ответа. Может принимать одно из значений: `info`, `warning`, `error`, `critical`
message.text	string	Да	Текст ответа, длина от 1 до 255 ASCII-символов

Отображение ответа в виде модального окна (visibility: "alert") требует поддержки на стороне клиентского приложения.

Ответ на запрос — стандартный ответ типа 2.