Reply Keyboard в n8n: Полное руководство по созданию и использованию клавиатур ответов в автоматизации мессенджеров
Reply Keyboard (Клавиатура ответов) — это инструмент в n8n, предназначенный для создания структурированных, предопределенных интерфейсов ввода для пользователей в мессенджерах, таких как Telegram, WhatsApp, Facebook Messenger и других. В отличие от Inline Keyboard, клавиатура ответов отображается непосредственно в поле ввода сообщения, заменяя стандартную клавиатуру устройства. Она является фундаментальным элементом для создания чат-ботов, опросов, навигационных меню и систем, требующих строго определенных ответов от пользователя. В n8n работа с Reply Keyboard осуществляется преимущественно через ноды соответствующих мессенджеров (например, Telegram, WhatsApp) с использованием функционала Expression Editor для форматирования данных клавиатуры.
Архитектура и принцип работы Reply Keyboard в n8n
Reply Keyboard в n8n не является отдельной нодой, а представляет собой специфический формат данных, который передается в качестве параметра при отправке сообщения через ноду мессенджера. Клавиатура создается динамически внутри workflow, что позволяет изменять ее структуру в зависимости от контекста, данных из базы данных или действий пользователя. Основной принцип заключается в формировании массива массивов строк (или объектов с дополнительными параметрами), который затем сериализуется в JSON и передается в поле `reply_markup` (для Telegram) или аналогичное поле в других сервисах.
Типичный workflow с использованием Reply Keyboard включает следующие шаги:
- Триггер: Нода, инициирующая процесс (Webhook, опрос Telegram, крон).
- Логика: Ноды для обработки данных, принятия решений (IF, Switch) или получения информации из БД.
- Формирование клавиатуры: Создание структуры клавиатуры с помощью Code Node или непосредственно в Expression Editor ноды мессенджера.
- Отправка сообщения: Нода мессенджера, которая отправляет текст и прикрепленную клавиатуру пользователю.
- Обработка ответа: Последующий триггер (например, новый Webhook) для приема и обработки нажатой пользователем кнопки.
Создание Reply Keyboard: Практические методы
Существует два основных метода создания Reply Keyboard в n8n: прямое кодирование в Expression Editor и динамическая генерация через Code Node.
Метод 1: Прямое формирование в Expression Editor ноды Telegram
Этот метод подходит для статических или простых клавиатур. В ноде Telegram, в разделе «Additional Fields» (Дополнительные поля), необходимо найти поле `reply_markup` и активировать Expression Editor. Клавиатура описывается на языке JSON.
Пример кода для простой клавиатуры 2×2:
{
"keyboard": [
["Кнопка 1", "Кнопка 2"],
["Кнопка 3", "Кнопка 4"]
],
"resize_keyboard": true,
"one_time_keyboard": false
}
Метод 2: Динамическая генерация через Code Node (JavaScript)
Этот метод предоставляет максимальную гибкость. Клавиатура формируется скриптом на основе внешних данных.
Пример кода в Code Node для создания клавиатуры из списка товаров:
const items = $input.all()[0].json.products; // Предполагаем, что предыдущая нода передала массив товаров
const keyboardRows = [];
let currentRow = [];
// Разбиваем товары на ряды по 2 кнопки
items.forEach((product, index) => {
currentRow.push(product.name);
if ((index + 1) % 2 === 0 || index === items.length - 1) {
keyboardRows.push([...currentRow]);
currentRow = [];
}
});
const replyMarkup = {
keyboard: keyboardRows,
resize_keyboard: true,
one_time_keyboard: true
};
// Возвращаем новый объект с данными для следующей ноды
return [{
json: {
replyMarkup: replyMarkup,
messageText: "Выберите товар из списка:"
}
}];
Затем в ноде Telegram в поле `reply_markup` указывается `{{ $json.replyMarkup }}`, а в поле `text` — `{{ $json.messageText }}`.
Ключевые параметры и конфигурация Reply Keyboard
Объект `reply_markup` для Reply Keyboard содержит несколько важных свойств, управляющих ее поведением и отображением.
| Параметр | Тип | Описание | Пример значения |
|---|---|---|---|
| keyboard | Array of Array of String | Основной массив, определяющий расположение кнопок. Каждый вложенный массив представляет собой ряд кнопок. | [ [«Да», «Нет»], [«Справка»] ] |
| resize_keyboard | Boolean | Опционально. Указывает клиенту изменить размер клавиатуры для оптимального отображения (уменьшить, если кнопок мало). По умолчанию false. | true |
| one_time_keyboard | Boolean | Опционально. Указывает, что клавиатура должна быть скрыта после первого использования. По умолчанию false. | true |
| selective | Boolean | Опционально. Используется, чтобы показать клавиатуру только определенным пользователям. Актуально в групповых чатах. | false |
Обработка ответов пользователя (нажатий кнопок)
Когда пользователь нажимает кнопку Reply Keyboard, мессенджер отправляет в n8n текстовое сообщение, содержащее ровно тот текст, который был указан на кнопке. Для обработки этого ответа необходимо:
- Настроить триггер (например, Telegram Webhook) на прием входящих сообщений.
- В workflow добавить ноду для обработки полученного текста. Чаще всего используется нода «Switch» (Переключатель).
- В ноде «Switch» настроить правила (Rules) на основе поля `message.text` (для Telegram). Каждое правило соответствует тексту с определенной кнопки и направляет поток выполнения по соответствующей ветке workflow.
- В каждой ветке реализовать необходимую бизнес-логику: запись в базу данных, формирование нового сообщения с новой клавиатурой, вызов внешнего API и т.д.
Расширенные сценарии использования
1. Многоуровневое меню
Клавиатура может меняться в зависимости от выбора пользователя, создавая иерархическую навигацию. После выбора пункта в главном меню, workflow отправляет новое сообщение с клавиатурой, соответствующей выбранному подразделу.
2. Интеграция с базами данных
Содержимое клавиатуры может динамически подгружаться из PostgreSQL, MySQL или Google Sheets. Например, клавиатура для выбора города или текущих акционных товаров.
3. Запрос контактных данных или местоположения
Telegram API поддерживает специальные типы кнопок в Reply Keyboard: для запроса номера телефона и для запроса геолокации. Для этого в массив кнопок вместо строки передается объект.
Пример кода для запроса контакта и локации:
{
"keyboard": [
[{"text": "Отправить номер телефона", "request_contact": true}],
[{"text": "Отправить местоположение", "request_location": true}],
["Отмена"]
],
"resize_keyboard": true,
"one_time_keyboard": true
}
Полученные контакт или местоположение будут содержаться в полях `message.contact` и `message.location` входящего обновления.
Сравнение Reply Keyboard и Inline Keyboard в контексте n8n
| Критерий | Reply Keyboard | Inline Keyboard |
|---|---|---|
| Место отображения | В поле ввода сообщения, заменяет системную клавиатуру. | Внутри чата, под связанным сообщением. |
| Тип взаимодействия | Отправляет текстовое сообщение с текстом кнопки. | |
| Гибкость отображения | Менее гибкая, кнопки только в виде текста (или спец. кнопки для контакта/локации). | Высокая: кнопки могут содержать URL-ссылки, вызывать callback-запросы с данными. |
| Сложность реализации в n8n | Проще, так как обработка сводится к анализу текста сообщения. | Сложнее, требует настройки обработки Callback Query и возможного редактирования исходного сообщения. |
| Идеальный use-case | Меню бота, опросы, запрос структурированных текстовых ответов, ввод данных. | Интерактивные элементы внутри чата (переключение страниц, выбор вариантов без засорения чата), кнопки-ссылки. |
Типичные ошибки и отладка
- Неверный формат JSON: Самая частая ошибка. Необходимо использовать валидатор JSON. В Expression Editor следует использовать обратные кавычки (`) для многострочных JSON.
- Клавиатура не отображается: Проверить, что параметр `reply_markup` передан корректно и является объектом, а не строкой. Убедиться, что в поле `keyboard` находится массив массивов.
- Кнопки не обрабатываются: Убедиться, что триггер (Webhook) настроен правильно и workflow обрабатывает входящие сообщения. Проверить логи n8n на наличие ошибок.
- Проблемы с кодировкой: Для кириллицы явно указывать кодировку в Code Node или использовать Unicode escape-последовательности, если возникают проблемы (редко в n8n).
Ответы на часто задаваемые вопросы (FAQ)
Вопрос: Как скрыть Reply Keyboard после использования?
Чтобы скрыть клавиатуру, необходимо отправить сообщение с параметром `reply_markup`, содержащим объект с единственным свойством `remove_keyboard: true`. В Expression Editor ноды Telegram это выглядит так: { "remove_keyboard": true }. Параметр `selective` также может быть использован для избирательного скрытия.
Вопрос: Можно ли изменить клавиатуру в уже отправленном сообщении?
Нет, в отличие от Inline Keyboard, Reply Keyboard привязана к конкретному отправленному сообщению и не может быть изменена программно. Чтобы «изменить» меню, необходимо отправить пользователю новое сообщение с новой клавиатурой.
Вопрос: Как создать клавиатуру с кнопками разной ширины?
Ширина кнопок в Reply Keyboard определяется структурой массива `keyboard`. Каждый подмассив — это ряд. Если вы хотите сделать кнопку на всю ширину, поместите ее строку в отдельный подмассив: [ ["Широкая кнопка"], ["Кнопка 1", "Кнопка 2"] ]. Первая кнопка будет занимать всю строку.
Вопрос: Работает ли Reply Keyboard в групповых чатах?
Да, но с ограничениями. По умолчанию клавиатура, отправленная в группу, будет видна всем участникам. Чтобы показать ее только конкретному пользователю (например, в ответ на команду), используйте параметр `selective: true`. Однако механика может отличаться в разных мессенджерах.
Вопрос: Как ограничить использование клавиатуры одним пользователем или сессией?
n8n, будучи серверной платформой, позволяет реализовать эту логику. Необходимо хранить идентификатор чата (`chat.id`) и текущее «состояние» пользователя (например, в переменных workflow, в базе данных или в памяти). Перед обработкой нажатия кнопки следует проверять, что идентификатор чата и состояние соответствуют ожидаемым, и что клавиатура была отправлена этому же пользователю.
Вопрос: Каков лимит на количество кнопок в Reply Keyboard?
Официальные ограничения зависят от мессенджера. Для Telegram клавиатура не может быть больше 8×8 (8 рядов по 8 кнопок в каждом). Рекомендуется делать клавиатуры компактными (3-4 ряда по 2-4 кнопки) для удобства пользователей. Слишком большие клавиатуры могут быть некорректно отображены на устройствах с маленьким экраном.
Вопрос: Можно ли использовать эмодзи и специальные символы в тексте кнопок?
Да, можно использовать эмодзи и любые UTF-8 символы, поддерживаемые мессенджером. Их следует просто вставить в строку текста кнопки при формировании массива `keyboard`.
Комментарии