N8n и интерактивные кнопки в Telegram: Полное руководство по автоматизации взаимодействия
N8n — это платформа с открытым исходным кодом для оркестрации рабочих процессов (workflow automation), которая позволяет соединять различные приложения и сервисы без написания кода. Интеграция N8n с Telegram открывает широкие возможности для создания чат-ботов, систем уведомлений и автоматизации коммуникаций. Ключевым элементом для создания интерактивного и удобного интерфейса в Telegram-боте являются кнопки. Они значительно повышают удобство использования, предоставляя пользователям готовые варианты действий вместо необходимости ввода текстовых команд.
Типы кнопок в Telegram Bot API
Telegram Bot API поддерживает несколько типов интерактивных кнопок, каждый из которых имеет свое назначение и особенности реализации в N8n.
- Reply Keyboard (Клавиатура ответа): Временная клавиатура, которая появляется вместо стандартной клавиатуры ввода текста. Используется для предоставления пользователю набора предопределенных вариантов ответа. Может быть скрыта пользователем.
- Inline Keyboard (Встроенная клавиатура): Кнопки, которые прикрепляются к конкретному сообщению. Они не исчезают после нажатия и могут использоваться для навигации, выбора опций или вызова callback-запросов без отправки нового сообщения в чат.
- Inline Keyboard с URL: Разновидность встроенной клавиатуры, где кнопки содержат ссылки на внешние веб-ресурсы.
- Кнопки для оплаты (Payment): Специализированные кнопки для запуска процесса оплаты через Telegram.
- Keyboard: Определяет массив строк кнопок. Каждый вложенный массив представляет собой строку в клавиатуре.
- Resize Keyboard (Опционально): Если true, клавиатура будет автоматически подстраиваться под размер кнопок.
- One Time Keyboard (Опционально): Если true, клавиатура будет скрыта после первого использования.
- Selective (Опционально): Показывать клавиатуру только определенным пользователям или в ответ на конкретное сообщение.
Настройка Telegram-бота и подключение к N8n
Перед созданием кнопок необходимо создать бота и получить его токен. Это выполняется через BotFather в Telegram. В N8n используется узел «Telegram Trigger» для получения обновлений (webhook) или узел «Telegram» для отправки сообщений. Для работы с webhook требуется публичный HTTPS-адрес вашего инстанса N8n или использование туннелирующих сервисов (ngrok, localtunnel).
Создание Reply Keyboard в N8n
Reply Keyboard создается с помощью узла «Telegram» в N8n в операции «sendMessage». В разделе «Additional Fields» необходимо развернуть опцию «Reply Markup» и выбрать «Reply Keyboard».
Пример настройки JSON для Reply Keyboard в поле «Reply Markup»:
{
"keyboard": [
["Опция 1", "Опция 2"],
["Справка", "Отмена"]
],
"resize_keyboard": true,
"one_time_keyboard": false
}
Создание Inline Keyboard в N8n
Inline Keyboard является более мощным инструментом. Она настраивается также в поле «Reply Markup» узла «Telegram», но с выбором типа «Inline Keyboard». Каждая кнопка имеет обязательный параметр `text` (отображаемый текст) и один из параметров: `callback_data`, `url` или `switch_inline_query`.
| Параметр кнопки | Тип | Описание | Пример значения |
|---|---|---|---|
| text | Строка | Текст, отображаемый на кнопке. | «Подтвердить» |
| callback_data | Строка (1-64 байта) | Данные, которые будут отправлены в N8n при нажатии на кнопку. Обрабатываются узлом «Telegram Trigger». | «action_approve_123» |
| url | Строка (URL) | HTTP- или tg://-ссылка, которая откроется при нажатии. | «https://example.com» |
| switch_inline_query | Строка | Запрос для переключения на inline-режим бота. | «поиск» |
Пример JSON для Inline Keyboard с callback-данными:
{
"inline_keyboard": [
[
{"text": "Статус заказа", "callback_data": "status_check"},
{"text": "Поддержка", "callback_data": "support"}
],
[
{"text": "Наш сайт", "url": "https://n8n.io"}
]
]
}
Обработка нажатий на Inline Keyboard (Callback Query)
Когда пользователь нажимает на inline-кнопку с `callback_data`, Telegram отправляет на ваш webhook объект `callback_query`. В N8n для его обработки необходимо использовать узел «Telegram Trigger».
- Настройте узел «Telegram Trigger» на событие «Callback Query».
- При нажатии на кнопку узел активирует следующий за ним workflow.
- Данные из `callback_data` доступны в выражении
{{ $node["Telegram Trigger"].json["callback_query"]["data"] }}. - Важно ответить на callback-запрос, чтобы убрать индикатор загрузки у пользователя. Для этого используется узел «Telegram» с операцией «answerCallbackQuery». В поле «Callback Query ID» нужно передать
{{ $node["Telegram Trigger"].json["callback_query"]["id"] }}.
Динамическое создание кнопок на основе данных
Мощь N8n раскрывается при генерации клавиатур на основе внешних данных. Например, можно создать меню из кнопок, где каждая кнопка соответствует товару из базы данных Google Sheets или записи из Airtable.
- Используйте узел (например, «Google Sheets» или «Airtable») для получения списка элементов.
- С помощью узла «Function» или «Code» преобразуйте массив данных в структуру `inline_keyboard` или `keyboard`.
- Передайте сгенерированный JSON в узел «Telegram» для отправки сообщения с клавиатурой.
Пример кода в узле «Function» для создания inline-кнопок из массива категорий:
const categories = items.map(item => {
return [{
text: item.name,
callback_data: `cat_${item.id}`
}];
});
return [{ inline_keyboard: categories }];
Практические примеры рабочих процессов (Workflows)
Пример 1: Опрос (Poll) с помощью Inline Keyboard
Workflow создает сообщение с вопросом и кнопками-вариантами ответа. Нажатие на кнопку регистрирует голос и обновляет результаты.
- Узел «Telegram»: Отправляет сообщение с inline-клавиатурой, где каждая кнопка имеет `callback_data` в формате `vote_option1`.
- Узел «Telegram Trigger»: Слушает событие «Callback Query».
- Узел «Function»: Обрабатывает голос (например, сохраняет в переменную контекста или внешнюю БД).
- Узел «Telegram»: Использует операцию «editMessageText» для обновления исходного сообщения, отображая обновленные счетчики голосов. Клавиатура при этом остается.
- Параллельно, узел «Telegram»: Отвечает на callback-запрос с помощью «answerCallbackQuery», чтобы уведомить пользователя, что его голос учтен.
Пример 2: Многоуровневое меню навигации
Создание сложного меню, где нажатие на кнопку приводит к замене сообщения и клавиатуры на новые (меню следующего уровня).
- Главное меню отправляется с кнопками: «Услуги», «Контакты», «О нас».
- При нажатии на «Услуги» (`callback_data: «menu_services»`), workflow обрабатывает запрос.
- Узел «Telegram» с операцией «editMessageText» изменяет текст исходного сообщения на список услуг и заменяет inline-клавиатуру на новую, где каждая услуга — это кнопка с `callback_data: «service_detail_X»`, а также добавляется кнопка «Назад» с `callback_data: «menu_main»`.
- Кнопка «Назад» обрабатывается аналогично, возвращая пользователя к предыдущему меню через `editMessageText`.
Ограничения и лучшие практики
- Размер callback_data: Ограничен 1-64 байта. Для передачи сложных данных используйте уникальные идентификаторы, а детали запрашивайте из базы данных в workflow.
- Ответ на callback_query: Всегда отвечайте на запрос в течение 30 секунд, иначе Telegram покажет пользователю алерт «ошибка».
- Частота обновлений: При использовании `editMessageText` для обновления сообщения с кнопками учитывайте ограничения по частоте запросов к API Telegram.
- Безопасность: Не доверяйте данным из `callback_data` без проверки. Злоумышленник может отправить произвольные данные. Всегда валидируйте и авторизуйте действия пользователя.
- Удобство: Делайте кнопки логичными и предсказуемыми. Используйте кнопку «Назад» в многоуровневых меню. Для Reply Keyboard предусмотрите команду «/cancel» для отмены текущего действия.
Ответы на часто задаваемые вопросы (FAQ)
Как скрыть Reply Keyboard?
Чтобы скрыть Reply Keyboard, необходимо отправить сообщение с параметром «Reply Markup» типа «Reply Keyboard Remove». В N8n для этого в узле «Telegram» в поле «Reply Markup» выберите «Reply Keyboard Remove» и установите `remove_keyboard: true`. Опционально можно использовать параметр `selective`.
Почему мои inline-кнопки не реагируют на нажатие?
Проверьте следующие пункты:
- Убедитесь, что узел «Telegram Trigger» настроен на событие «Callback Query» и webhook работает корректно.
- Проверьте, что вы отвечаете на callback-запрос с помощью узла «answerCallbackQuery». Без этого у пользователя может остаться индикатор загрузки.
- Убедитесь, что в `callback_data` нет недопустимых символов или превышения лимита в 64 байта.
- Проверьте, что бот имеет необходимые разрешения в чате.
Можно ли изменить кнопки в уже отправленном сообщении?
Да, но только для сообщений с Inline Keyboard. Используйте узел «Telegram» с операцией «editMessageReplyMarkup». Вам необходимо указать Chat ID, Message ID и новые параметры клавиатуры в поле «Reply Markup». Message ID можно получить из исходного сообщения, которое было отправлено ботом.
Как отправить и кнопки, и медиафайл (фото, документ)?
При отправке медиафайлов (операции «sendPhoto», «sendDocument» и др.) в узле «Telegram» также доступно поле «Reply Markup». Алгоритм добавления кнопок идентичен отправке текстового сообщения. Клавиатура будет отображена под медиафайлом в чате.
Есть ли ограничение на количество кнопок в клавиатуре?
Для Reply Keyboard: максимальное количество кнопок — 12 в строке, количество строк не ограничено, но интерфейс должен оставаться удобным. Для Inline Keyboard: максимальное количество кнопок в строке — 8, максимальное количество строк — зависит от высоты экрана, но рекомендуется не более 10-12 строк. Общее практическое правило — не более 100 кнопок на сообщение.
Как реализовать «кнопку-ссылку» для открытия веб-приложения?
Используйте Inline Keyboard с параметром `url`. Ссылка может быть обычным HTTP/HTTPS URL. Для открытия Mini Apps в Telegram используйте специальный протокол `https://t.me/{bot_username}/{app_short_name}` или `tg://resolve?domain=…`. Убедитесь, что ваш бот настроен для работы с Mini Apps.
Комментарии