N8n Inline Keyboard: Полное руководство по созданию интерактивных кнопок в Telegram-ботах

Inline Keyboard (встроенная клавиатура) в n8n — это механизм создания интерактивных кнопок непосредственно под сообщением в мессенджерах, в первую очередь в Telegram. В отличие от Reply Keyboard, которая появляется вместо основной клавиатуры устройства, inline-кнопки являются частью контента сообщения и не занимают место на экране. Их основное назначение — предоставление пользователю структурированного интерфейса для взаимодействия с ботом без необходимости ввода текстовых команд.

Архитектура и принцип работы Inline Keyboard в n8n

Реализация inline keyboard в n8n базируется на использовании ноды Telegram и ее операций. Клавиатура создается как массив массивов объектов (кнопок) в свойстве reply_markup при отправке сообщения. Каждая кнопка содержит обязательные и опциональные поля, определяющие ее текст, действие (callback_data, url) и другие параметры.

Типичный рабочий процесс (workflow) с inline keyboard состоит из двух ключевых этапов:

• Отправка сообщения с клавиатурой: Используется нода Telegram с операцией «Send Message». В параметрах сообщения формируется объект reply_markup, содержащий структуру клавиатуры.
• Обработка нажатия на кнопку: Используется нода Telegram с операцией «Webhook» или в режиме Polling. При нажатии пользователем на кнопку Telegram отправляет на ваш вебхук или нода получает обновление, содержащее уникальный идентификатор callback_query. Этот идентификатор включает данные кнопки (callback_data), которые необходимо обработать в workflow.

Создание и настройка Inline Keyboard

Для формирования клавиатуры в ноде «Send Message» необходимо перейти в поле «Reply Markup» и выбрать режим «Keyboard». Далее следует использовать выражение для определения структуры.

Структура объекта клавиатуры

Базовая структура на языке JSON выглядит следующим образом:

{
  "inline_keyboard": [
    [
      { "text": "Кнопка 1", "callback_data": "action_1" },
      { "text": "Кнопка 2", "callback_data": "action_2" }
    ],
    [
      { "text": "Кнопка 3", "callback_data": "action_3" }
    ]
  ]
}
    

В n8n это выражение обычно задается в поле «Keyboard» с помощью формата JSON или конструктора выражений (Expression Editor). Каждый вложенный массив представляет собой ряд (row) кнопок. Количество кнопок в ряду определяется автоматически, но для лучшего отображения рекомендуется не более 3-4 кнопок в ряду для стандартных экранов.

Типы кнопок Inline Keyboard

Обработка Callback Data в n8n

Когда пользователь нажимает на callback-кнопку, n8n получает обновление типа callback_query. Для его обработки необходимо:

1. Настроить ноду Telegram на триггер «Webhook» (рекомендуется) или «Polling».
2. Подключить после нее ноду «Switch» или «IF» для ветвления workflow в зависимости от значения callback_data.
3. Извлечь данные из входящего обновления. Путь к данным: {{$json.callback_query.data}}.
4. Важно ответить на callback-запрос с помощью ноды Telegram с операцией «Answer Callback Query», чтобы убрать индикатор загрузки у пользователя. Можно также отредактировать исходное сообщение или отправить новое.

Пример workflow для обработки нажатия

Триггер: Telegram Node (Webhook) -> Условие: Switch Node (по $json.callback_query.data) -> Действие 1: Answer Callback Query + Send Message -> Действие 2: Answer Callback Query + Edit Message Text.

Продвинутые техники и лучшие практики

Динамическое формирование клавиатуры

Клавиатуру можно генерировать на основе данных из предыдущих нод (например, из базы данных или API). Используйте ноду «Function» или «Function Item» для создания переменной с массивом кнопок.

// Пример в Function Node для создания клавиатуры из списка товаров
const items = $input.all();
const keyboard = { inline_keyboard: [] };
let row = [];

items.forEach((item, index) => {
  row.push({
    text: item.json.name,
    callback_data: `select_product_${item.json.id}`
  });
  // Создаем новый ряд каждые 2 кнопки
  if ((index + 1) % 2 === 0) {
    keyboard.inline_keyboard.push(row);
    row = [];
  }
});

if (row.length > 0) {
  keyboard.inline_keyboard.push(row);
}

return { json: { dynamicKeyboard: keyboard } };
    

Редактирование сообщения с клавиатурой

Вместо отправки нового сообщения можно отредактировать существующее, изменив текст и/или клавиатуру. Используйте операцию «Edit Message Text» в ноде Telegram. Необходимо передать chat_id, message_id и новый reply_markup. Это полезно для создания многошаговых интерфейсов (wizards) или обновления состояния (например, кнопка «Выполнено» становится неактивной).

Пагинация с помощью Inline Keyboard

Реализуется путем включения в callback_data информации о текущей странице (например, page_2). При нажатии на кнопки «Вперед»/»Назад» workflow загружает новые данные, формирует новую клавиатуру и редактирует исходное сообщение.

Ограничения и особенности

• Размер callback_data: Не более 64 байт. Рекомендуется использовать сжатые идентификаторы (ID, коды действий).
• Частота нажатий: Telegram может ограничивать частоту отправки callback-ответов.
• Состояние кнопок: Inline keyboard не имеет встроенного визуального состояния «нажата». Состояние необходимо имитировать путем редактирования сообщения (например, меняя текст кнопки или добавляя символ «✔»).
• Безопасность: callback_data передается в открытом виде. Не следует помещать в нее конфиденциальную информацию. Всегда проверяйте входящие данные на стороне workflow.

Интеграция с другими нодами и сервисами

Мощь n8n раскрывается при комбинации inline keyboard с другими нодами. Примеры интеграций:

• Базы данных (PostgreSQL, MySQL): Кнопки для подтверждения/отклонения записи. callback_data содержит ID записи и действие.
• Google Sheets: Отправка строк из таблицы в виде кнопок для выбора.
• Внешние API (CRM, Jira, Trello): Создание интерактивного меню для управления задачами или лидами.
• Логика (IF, Switch): Сложное ветвление сценариев на основе нажатой кнопки.

Часто задаваемые вопросы (FAQ)

Вопрос: Почему моя клавиатура не отображается в Telegram?

Ответ: Проверьте следующие пункты:

• Корректность синтаксиса JSON в поле «Reply Markup». Используйте валидатор JSON.
• Указан ли правильный режим «Keyboard» (не «Reply» или «Force Reply»).
• Не превышает ли общее количество кнопок или их текст разумные пределы (Telegram может не отображать слишком большие клавиатуры).

Вопрос: Как сделать, чтобы кнопка исчезла после нажатия?

Ответ: Inline keyboard сама не исчезает. Вам необходимо отредактировать сообщение с помощью операции «Edit Message Text» и передать новый объект reply_markup с измененной клавиатурой (например, удалив нажатую кнопку или заменив ее текст) или вовсе убрать клавиатуру, установив reply_markup: {}.

Вопрос: Можно ли использовать inline keyboard в других мессенджерах через n8n?

Ответ: Концепция inline keyboard специфична для Telegram API. Однако аналогичные интерактивные элементы существуют в других платформах (например, Quick Replies в WhatsApp, Interactive Messages в Slack). В n8n для работы с ними используются соответствующие ноды (WhatsApp Business, Slack и т.д.), и принцип формирования интерфейса будет отличаться.

Вопрос: Как обработать нажатие двух разных кнопок одновременно от разных пользователей?

Ответ: Workflow n8n обрабатывает каждое обновление (нажатие кнопки) как отдельный экземпляр выполнения. Благодаря уникальному callback_query.id и изолированному контексту каждого запуска, конфликтов не возникает. Убедитесь, что ваша логика не зависит от глобальных переменных без должной синхронизации.

Вопрос: Есть ли ограничение на количество кнопок в клавиатуре?

Ответ: Строгого ограничения в документации Telegram нет, но существует практический предел из-за размера сообщения и удобства использования. Рекомендуется не создавать клавиатуры, которые занимают более половины экрана мобильного устройства. Также помните об ограничении в 64 байта для callback_data каждой кнопки.

Вопрос: Как отправить одно сообщение с клавиатурой нескольким пользователям?

Ответ: Вам потребуется цикл (например, с использованием ноды «Loop Over Items» или «For Each») по списку chat_id. Для каждого chat_id выполните операцию «Send Message» с одним и тем же объектом клавиатуры. Учтите лимиты Telegram на отправку сообщений.

Заключение

Inline keyboard в n8n представляет собой мощный инструмент для создания полноценных графических интерфейсов внутри Telegram-ботов. Комбинируя отправку структурированных клавиатур, обработку callback-данных и редактирование сообщений, можно реализовать сложные интерактивные сценарии: от простых меню и опросов до многостраничных каталогов и систем управления. Понимание архитектуры, ограничений и лучших практик, изложенных в данной статье, позволит эффективно интегрировать этот функционал в свои автоматизированные workflow, значительно повышая удобство взаимодействия пользователей с ботами.