N8n telegram reply markup expression code

N8n Telegram Reply Markup Expression Code: Полное руководство

Интеграция мессенджера Telegram в автоматизированные рабочие процессы (workflows) через платформу n8n предоставляет мощные возможности для взаимодействия с пользователями. Ключевым элементом этого взаимодействия является создание интерактивных интерфейсов — кнопок, которые появляются под сообщением. В Telegram Bot API этот функционал называется Reply Markup, а в n8n для его тонкой настройки используется Expression Editor и язык кода. Данная статья детально рассматривает принципы работы, синтаксис и практическое применение Reply Markup Expression Code в нодах Telegram.

Основы Reply Markup в Telegram Bot API

Reply Markup — это специальный объект, который передается вместе с сообщением бота. Он определяет, какие кнопки и в какой конфигурации увидит пользователь. Существует три основных типа разметки:

InlineKeyboardMarkup: Кнопки, которые встраиваются непосредственно в сообщение. При нажатии они генерируют callback_data, обрабатываемую ботом, не отправляя новое сообщение в чат.
ReplyKeyboardMarkup: Клавиатура, которая появляется вместо стандартной клавиатуры устройства. Может быть скрыта пользователем. Кнопки отправляют свой текст как сообщение в чат.
ReplyKeyboardRemove: Специальная инструкция для удаления текущей Reply-клавиатуры.
ForceReply: Инструкция, принудительно предлагающая пользователю ответить на конкретное сообщение.

В нодах n8n «Telegram Trigger» и «Telegram» (для отправки сообщений) есть поля для настройки клавиатуры. Часто простые варианты можно выбрать через интерфейс, но для полного контроля, динамического создания кнопок или работы с callback_data необходимо использовать Expression Editor.

Expression Editor и синтаксис для Reply Markup

Expression Editor в n8n позволяет использовать JavaScript-подобный код для генерации динамических значений. Для создания Reply Markup необходимо сформировать корректный объект JSON, соответствующий спецификации Telegram API.

Создание InlineKeyboardMarkup через Expression Code

Inline-клавиатура представляет собой массив рядов кнопок, где каждый ряд — это массив объектов кнопок. Базовая структура:

{
  "inline_keyboard": [
    [
      { "text": "Кнопка 1", "callback_data": "action_1" },
      { "text": "Кнопка 2", "callback_data": "action_2" }
    ],
    [
      { "text": "Сайт", "url": "https://example.com" }
    ]
  ]
}

В Expression Editor ноды «Send Message» (Telegram) это будет выглядеть так:

{{{
{
  "inline_keyboard": [
    [ { "text": "Подтвердить", "callback_data": "confirm_order_123" } ],
    [ { "text": "Открыть справку", "url": "https://help.site.com" } ]
  ]
}
}}}

Создание ReplyKeyboardMarkup через Expression Code

Reply-клавиатура имеет схожую структуру, но с другими свойствами и дополнительными параметрами:

{
  "keyboard": [
    [ { "text": "Опция A" }, { "text": "Опция B" } ],
    [ { "text": "Отправить контакт", "request_contact": true } ],
    [ { "text": "Отправить локацию", "request_location": true } ]
  ],
  "resize_keyboard": true,
  "one_time_keyboard": false,
  "selective": false
}

Параметры:

resize_keyboard: Автоматически подгонять размер клавиатуры.
one_time_keyboard: Скрывать клавиатуру после одного использования.
selective: Показывать клавиатуру только определенным пользователям.

Динамическая генерация клавиатур

Мощь Expression Editor раскрывается при создании клавиатур на основе данных из предыдущих нод workflow.

Пример 1: Клавиатура из данных базы данных

Предположим, нода «PostgreSQL» получила список категорий товаров. Нужно создать inline-клавиатуру с этими категориями.

{{{
const categories = $json["PostgreSQL"].items;
const keyboardRows = [];
for (const cat of categories) {
  keyboardRows.push([{ text: cat.name, callback_data: `cat_${cat.id}` }]);
}
return { inline_keyboard: keyboardRows };
}}}

Пример 2: Условное создание кнопок

Клавиатура может меняться в зависимости от состояния или прав пользователя.

{{{
const userRole = $input.first().json.userRole;
const baseKeyboard = [ [ { "text": "Общая информация", "callback_data": "info" } ] ];
if (userRole === "admin") {
  baseKeyboard.unshift([ { "text": "Админ панель", "callback_data": "admin_panel" } ]);
}
return { inline_keyboard: baseKeyboard };
}}}

Обработка Callback Data в ноде Telegram Trigger

Когда пользователь нажимает на inline-кнопку, Telegram Trigger нода в n8n генерирует событие. Данные о нажатии доступны в поле callback_data.

Для обработки разных действий используйте ноду «Switch» или «IF», чтобы направить поток выполнения в зависимости от значения $json.callback_data.
Важно структурировать callback_data для удобного парсинга (например, "action:delete;id:123" или "delete_123").

Пример парсинга в Expression Editor последующей ноды:

{{{
const data = $json.callback_data;
if (data.startsWith('delete_')) {
  const itemId = data.split('_')[1];
  return { action: 'delete', id: itemId };
}
return {};
}}}

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

Использование Webhook для Callback Queries

Для мгновенного визуального отклика (например, убрать «часики» с кнопки или изменить сообщение) необходимо ответить на callback query. В n8n это делается с помощью ноды «Telegram» с операцией «Answer Callback Query». В поле callbackQueryId нужно указать $json.callback_query_id из триггера.

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

Нода «Telegram» с операцией «Edit Message Text» или «Edit Message Reply Markup» позволяет изменить существующее сообщение и его клавиатуру. Это полезно для создания многошаговых меню. В Expression Editor для новой клавиатуры можно использовать данные из предыдущих шагов.

Ограничения Telegram API

Параметр	Ограничение
Размер callback_data	До 64 байт
Количество кнопок в ряду (Inline)	До 8 кнопок
Количество рядов (Inline)	Фактически ограничено размером сообщения
Текст на кнопке Reply	До 4096 символов (практически не используется)

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

Вопрос 1: Почему моя клавиатура, созданная через Expression, не отображается?

Ответ: Проверьте следующее:

Корректность синтаксиса JSON в Expression Editor. Используйте инструменты валидации JSON.
Что вы используете правильные корневые ключи: inline_keyboard для inline и keyboard для reply-клавиатуры.
Что Expression возвращает объект, а не строку. Код должен быть обернут в {{{ ... }}}.
Логируйте вывод Expression с помощью ноды «Code» или «Set», чтобы увидеть, что именно генерируется.

Вопрос 2: Как передать в callback_data несколько параметров?

Ответ: Из-за ограничения в 64 байта используйте компактный формат. Например: "user:123;action:promote" или 123_promote. Затем разберите строку в workflow с помощью ноды «Code» или функций в Expression Editor (split(), match()).

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

Ответ: Да, структура массивов определяет ряды и колонки. Кнопка { text: "Широкая кнопка" }, помещенная в отдельный внутренний массив [ ... ], займет всю ширину. Две кнопки в одном внутреннем массиве будут расположены рядом.

Вопрос 4: Как полностью удалить Reply-клавиатуру?

Ответ: В Expression Editor для поля Reply Markup укажите: {{{ {"remove_keyboard": true, "selective": false} }}}. Параметр selective позволяет удалять клавиатуру выборочно.

Вопрос 5: Как обработать нажатие кнопки в Reply-клавиатуре?

Ответ: Кнопки Reply-клавиатуры не генерируют callback. Вместо этого текст на кнопке отправляется в чат как обычное сообщение пользователя. Обрабатывать его нужно в ноде Telegram Trigger на событие «Message». Далее можно фильтровать сообщения по тексту, используя ноду «IF».

Вопрос 6: Можно ли изменить клавиатуру у сообщения, отправленного ранее?

Ответ: Да, но только для inline-клавиатур. Используйте ноду «Telegram» с операцией «Edit Message Reply Markup». Вам понадобятся chat_id и message_id исходного сообщения. В Expression Editor для нового reply_markup сгенерируйте актуальный объект клавиатуры.

Заключение

Использование Expression Code для создания Reply Markup в n8n открывает уровень гибкости и контроля, недоступный при использовании только графического интерфейса. Понимание структур данных Telegram Bot API, умение генерировать динамические JSON-объекты и правильно обрабатывать callback-запросы являются ключевыми для построения сложных интерактивных ботов. Комбинируя ноды n8n и JavaScript-код в Expression Editor, можно создавать адаптивные меню, многошаговые формы и сложные интерфейсы, значительно улучшая пользовательский опыт взаимодействия с автоматизированными системами через Telegram.