Для разработчиков

Кнопки в сообщениях

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

Как это работает

Создайте бота

Откройте Интеграции > Боты и нажмите Создать бота. Подробнее — в разделе Создание бота.

Отправьте сообщение с кнопками

Используйте метод POSTНовое сообщение с полем buttons — массив строк, каждая из которых содержит массив кнопок.

Настройте исходящий вебхук

Для обработки Data-кнопок включите вебхук на вкладке Исходящий вебхук в карточке бота, указав URL своего сервера, и отметьте событие Нажатие кнопок. Подробнее — в разделе Исходящие вебхуки.

Обработайте нажатие

При нажатии Data-кнопки бот получает вебхук с данными кнопки. Обработайте событие и дайте обратную связь — отредактируйте сообщение, отправьте новое или откройте модальную форму.

Типы кнопок

Сообщение от бота с кнопками

URL-кнопки

URL-кнопка перенаправляет пользователя по указанной ссылке. При нажатии отображается модальное окно с подтверждением перехода. В нём можно отметить, чтобы ссылки на этот домен и его поддомены дальше открывались без подтверждения.

{  "text": "Все мои проекты",  "url": "https://example.com/projects"}

Подтверждение перехода по ссылке

Data-кнопки

Data-кнопка отправляет данные на сервер через исходящий вебхук. При нажатии бот получает вебхук с информацией о кнопке, сообщении и пользователе, что позволяет реализовать любую логику обработки.

{  "text": "👍 Согласиться",  "data": "vote_yes"}

Отправка кнопок

Сообщения с кнопками отправляют токеном бота: нажатие Data-кнопки приходит событием только тому боту, который отправил сообщение. Сами кнопки передаются методом POSTНовое сообщение в поле buttons. Поле представляет собой массив строк, каждая из которых содержит массив кнопок. В одной строке можно комбинировать URL-кнопки и Data-кнопки.

Сообщение с кнопками
pachca messages create \  --entity-id=334 \  --content='Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)' \  --files='[{"key":"attaches/files/93746/e354fd79-4f3e-4b5a-9c8d-1a2b3c4d5e6f/logo.png","name":"logo.png","file_type":"image","size":12345,"width":800,"height":600,"duration_ms":5400,"waveform":"4,8,12,20,16,10,6,3"}]' \  --buttons='[[{"text":"Подробнее","url":"https://example.com/details"},{"text":"Отлично!","data":"awesome"}]]' \  --parent-message-id=194270 \  --display-avatar-url=https://example.com/avatar.png \  --display-name='Бот Поддержки' \  --json \  --token YOUR_ACCESS_TOKEN

Метод PUTРедактирование сообщения также поддерживает поле buttons. Для удаления всех кнопок передайте пустой массив [].

Обработка нажатий

Для получения событий о нажатиях Data-кнопок настройте исходящий вебхук и включите событие Нажатие кнопок.

При нажатии кнопки бот получает вебхук:

ButtonWebhookPayloadobject

После получения события вы можете:

Ограничения

  • Максимальное количество кнопок в сообщении — 100
  • Максимальное количество строк с кнопками — 32
  • Количество кнопок в строке — от 1 до 8
  • Максимальная длина text на кнопке — 255 символов
  • Максимальная длина data у кнопки — 255 символов
  • Максимальная длина url у кнопки — 1024 символа
  • У кнопки заполнено ровно одно из полей url и data — оба сразу или ни одного дают ошибку wrong_params

Строка кнопок в интерфейсе не переносится, поэтому даже разрешённые восемь штук на узких экранах читаются плохо — держите в ряду пять-шесть.