N8n inline keyboard telegram

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

N8n — это платформа с открытым исходным кодом для оркестрации рабочих процессов (workflow automation), которая позволяет соединять различные приложения и сервисы без написания кода. Одной из ключевых интеграций является работа с Telegram Bot API, в частности, создание и управление inline-клавиатурами. Inline-клавиатура — это интерактивные кнопки, прикрепленные к конкретному сообщению в чате, в отличие от обычной клавиатуры, которая находится под полем ввода. Они используются для создания меню, опросов, навигации и обработки действий пользователя непосредственно в контексте диалога.

Основные компоненты Telegram Bot API для клавиатур в N8n

Для работы с клавиатурами в N8n через узел «Telegram» необходимо понимать два типа клавиатур:

• ReplyKeyboardMarkup: Стандартная клавиатура, которая появляется вместо поля ввода. Создается с помощью параметра `reply_markup` в методах отправки сообщений.
• InlineKeyboardMarkup: Инлайн-клавиатура, встроенная в само сообщение. Именно этот тип предоставляет богатые возможности для интерактива.

В N8n работа с inline-клавиатурой сосредоточена в узле «Telegram» и его операциях: «Send Message», «Send Photo», «Edit Message Text», «Answer Callback Query» и других.

Создание простой inline-клавиатуры в N8n

Базовая настройка узла «Telegram» для отправки сообщения с кнопками:

1. Добавьте узел «Telegram» в рабочий процесс.
2. Выберите операцию «Send Message» или «Send Photo».
3. В поле «Chat ID» укажите идентификатор чата (можно получить из предыдущих сообщений или через узел «Webhook»).
4. В поле «Text» введите текст сообщения.
5. Раскройте раздел «Additional Fields» и найдите поле «Reply Markup».
6. Выберите «Inline Keyboard» из выпадающего списка.
7. В появившемся интерфейсе «Inline Keyboard» создайте строки и кнопки. Для каждой кнопки необходимо указать:
   • Text: Текст, отображаемый на кнопке.
   • Callback Data: Уникальная строка данных (до 64 байт), которая будет отправлена вашему боту при нажатии на кнопку. Это ключевой параметр для обработки действий.

Пример структуры inline-клавиатуры 2×2 в интерфейсе N8n:

Row	Button Text	Callback Data	URL (опционально)
1	Опция A	action_a
1	Опция B	action_b
2	Открыть сайт		https://example.com
2	Запросить локацию	request_location

Обработка нажатий на кнопки (Callback Query)

Когда пользователь нажимает на inline-кнопку, Telegram отправляет вашему боту объект «Callback Query». В N8n для его обработки используется триггерный узел «Telegram Trigger».

1. Добавьте узел «Telegram Trigger» в начало рабочего процесса.
2. Настройте его на событие «Callback Query».
3. При наступлении события (нажатии кнопки) этот узел активирует следующий за ним узел, передавая данные о callback.
4. Ключевые данные, доступные в выходных данных узла:
   • callback_query.data — содержимое поля `callback_data` нажатой кнопки (например, «action_a»).
   • callback_query.message.message_id — ID сообщения, к которому прикреплена клавиатура. Необходимо для редактирования сообщения.
   • callback_query.id — уникальный идентификатор callback-запроса, необходимый для ответа.

Паттерны обработки действий

После получения `callback_query.data` рабочий процесс должен определить, какое действие запросил пользователь. Стандартная архитектура включает:

1. Ответ на callback-запрос

Telegram требует, чтобы бот явно ответил на каждый callback-запрос, даже если ответ пустой. Это убирает индикатор загрузки у пользователя. Используется узел «Telegram» с операцией «Answer Callback Query».

• Callback Query ID: Связывается с callback_query.id из триггера.
• Text: Опциональное уведомление, которое появится у пользователя в верхней части чата (тост).
• Show Alert: Если «true», уведомление будет отображено как модальное окно.

2. Редактирование исходного сообщения

Часто после нажатия кнопки нужно обновить сообщение: изменить текст, убрать клавиатуру или заменить ее на новую. Используется узел «Telegram» с операцией «Edit Message Text».

• Chat ID: callback_query.message.chat.id
• Message ID: callback_query.message.message_id
• Text: Новый текст сообщения.
• Reply Markup: Можно указать новую inline-клавиатуру или оставить поле пустым для удаления старой.

3. Создание сложной навигации (меню)

Используя комбинацию «Edit Message Text» и динамического формирования `reply_markup` в N8n, можно создавать многоуровневые меню. Данные о текущем меню или состоянии пользователя можно хранить в `callback_data` (например, `menu_main`, `menu_settings_1`) или во внешней базе данных, подключенной через соответствующие узлы N8n.

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

Мощь N8n раскрывается при генерации клавиатур из внешних данных. Пример: отправка списка товаров из Google Sheets, где каждый товар — кнопка.

1. Узел «Google Sheets» получает список товаров.
2. Узел «Function» или «Code» преобразует массив товаров в массив объектов для inline-клавиатуры, приемлемый для Telegram API.
3. Узел «Telegram» отправляет сообщение, где `reply_markup` берется из результата работы Function-узла.

Пример кода в Function-узле для создания клавиатуры из массива:

const items = $input.all();
const keyboard = [];
items.forEach(item => {
  keyboard.push([{
    text: item.json.productName,
    callback_data: `select_product_${item.json.id}`
  }]);
});
return { inline_keyboard: keyboard };

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

Структура Callback Data

Рекомендуется использовать структурированный формат `callback_data` для упрощения парсинга:

• Простой: action:value (например, `vote:yes`)
• Сложный: entity:action:id (например, `user:ban:12345`)

В Function-узле можно разбить строку с помощью split(':') и передать дальше по workflow.

Обработка таймаутов и ошибок

Callback-запросы должны быть обработаны в течение 30 секунд. В N8n необходимо следить за производительностью workflow. Используйте узел «Answer Callback Query» как можно раньше в цепочке, если дальнейшая обработка длительная.

Управление состоянием

Для сложных диалогов требуется сохранять контекст (state). Варианты в N8n:

Метод	Инструмент в N8n	Применение
Хранение в `callback_data`	Поле «Callback Data» кнопки	Простая навигация, ограничено 64 байтами.
Временное хранилище	Узлы «Set» и «Binary Data» (в памяти)	Кратковременное хранение в рамках одного выполнения workflow.
Внешние базы	Узлы PostgreSQL, SQLite, Redis, MongoDB	Постоянное хранение данных пользователей и их состояний.

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

Inline-клавиатура становится точкой входа для сложной автоматизации:

• Подтверждение действия: Кнопки «Подтвердить/Отменить» для запуска процесса в стороннем сервисе (например, создание заявки в Jira или отправка email через SendGrid).
• Выбор из списка: Динамические кнопки для выбора варианта из базы данных (выбор отдела, категории, даты).
• Интерактивные отчеты: Кнопки «Обновить», «Детализация», «Экспорт» под отправленным ботом отчетом.

Ответы на часто задаваемые вопросы (FAQ)

Как получить Chat ID для отправки сообщения?

Самый простой способ — отправить любое сообщение боту, а затем использовать узел «Telegram Trigger» со событием «Message». В выходных данных узла будет поле chat.id. Также можно использовать специальных ботов, таких как @userinfobot, для получения вашего Chat ID.

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

• Убедитесь, что в поле «Reply Markup» выбран именно «Inline Keyboard», а не «Keyboard».
• Проверьте формат данных, передаваемых в «Reply Markup». Это должен быть валидный JSON объект с ключом inline_keyboard.
• Клавиатура может быть автоматически скрыта, если вы не ответили на callback-запрос с помощью операции «Answer Callback Query».
• Если вы редактируете сообщение с помощью «Edit Message Text» и не передаете новый параметр `reply_markup`, старая клавиатура будет удалена.

Как создать кнопку с URL?

В интерфейсе настройки кнопки в N8n оставьте поле «Callback Data» пустым и заполните поле «URL». Telegram автоматически распознает такую кнопку как ссылку. Обратите внимание, что нажатие на URL-кнопку не генерирует callback-запрос.

Можно ли изменить inline-клавиатуру у уже отправленного сообщения?

Да, для этого используется операция «Edit Message Reply Markup». В параметрах необходимо указать Chat ID, Message ID и новую структуру клавиатуры в поле «Reply Markup». Это позволяет динамически обновлять меню без изменения текста сообщения.

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

Каждое нажатие создает уникальный `callback_query.id`. Ваш workflow, запущенный триггером, должен обрабатывать их независимо. Важно проектировать `callback_data` так, чтобы она содержала идентификатор целевого объекта (например, `task_123`), а логика workflow учитывала, кто нажал кнопку (callback_query.from.id). Для сложных сценариев необходима проверка прав доступа.

Есть ли ограничения на количество кнопок в inline-клавиатуре?

Да, ограничения накладывает Telegram Bot API:

• Максимальное количество кнопок в строке — 8.
• Максимальное количество строк — 100 (но на практике разумно использовать гораздо меньше).
• Размер данных в `callback_data` для одной кнопки — до 64 байт (1-64 символа в ASCII).
• Общий размер `reply_markup` не должен превышать 65536 байт.

Как отправить сообщение с inline-клавиатурой в групповой чат?

Принцип тот же, что и для личного чата. Необходимо указать Chat ID группы (обычно это отрицательное число). Бот должен быть добавлен в группу и иметь права на отправку сообщений. В групповых чатах callback-запросы будут содержать информацию о том, какой пользователь нажал кнопку.

Чем отличается Inline Keyboard от Reply Keyboard?

Критерий	Inline-клавиатура	Reply-клавиатура
Расположение	Встроена в сообщение.	Заменяет стандартную клавиатуру ввода.
Данные	Отправляет `callback_data` боту в фоне.	Отправляет текст кнопки как обычное сообщение.
Взаимодействие	Не захламляет историю чата.	Каждое нажатие добавляет сообщение в чат.
Сохранение	Может быть изменена или удалена у существующего сообщения.	Отправляется только с новым сообщением.