N8n telegram node

N8n Telegram Node: Полное руководство по интеграции и автоматизации

N8n — это инструмент с открытым исходным кодом для оркестрации рабочих процессов (workflow automation), который использует визуальный редактор на основе узлов (nodes). Telegram Node в N8n — это специализированный узел, который позволяет подключать рабочие процессы к мессенджеру Telegram, обеспечивая двустороннюю связь: получение сообщений из Telegram и отправку данных в него. Этот узел является критически важным для создания автоматизированных систем уведомлений, чат-ботов, мониторинга и сбора данных через популярный мессенджер.

Принцип работы и архитектура Telegram Node в N8n

Telegram Node в N8n функционирует через официальный Bot API, предоставляемый Telegram. Для работы необходимо создать бота через @BotFather и получить уникальный API-токен. В N8n существуют два основных типа узлов Telegram: триггерный узел (Telegram Trigger) и узел для выполнения действий (Telegram Node).

Триггерный узел «Telegram Trigger» работает на основе вебхуков (webhook) или длинного опроса (long polling). Он запускает рабочий процесс при наступлении определенного события в Telegram, таком как:

Получение нового сообщения в личном чате с ботом или в группе/канале (если бот является администратором).
Получение callback-запроса от inline-кнопки.
Добавление бота в чат.
Получение команды (например, /start).

Узел «Telegram» (исполнительный) используется для отправки сообщений, медиафайлов, управления чатами и реагирования на callback-запросы. Он не запускает workflow, а является действием внутри него.

Настройка и аутентификация

Для начала работы с любым узлом Telegram в N8n требуется создать ресурс (Resource) типа «Telegram». Это централизованная настройка учетных данных, которую можно повторно использовать в разных рабочих процессах.

Процесс настройки включает следующие шаги:

Создание бота в Telegram через @BotFather и получение токена (например, 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).
В N8n перейти в раздел «Credentials» -> «Add Credential».
Выбрать тип «Telegram API».
Ввести полученный токен в поле «Access Token».
При необходимости, для использования вебхуков, указать URL вашего инстанса N8n, если он работает на публичном сервере.

Важно: Для локальной разработки (localhost) использование вебхуков невозможно, так как Telegram сервера не могут до него «дотянуться». В этом случае в настройках триггера следует выбрать «Polling». Для продакшена на VPS или облачном хостинге с публичным IP/доменом предпочтительнее использовать «Webhook».

Детальный обзор возможностей и операций Telegram Node

Узел «Telegram» (исполнительный) поддерживает широкий спектр операций. Каждая операция соответствует конкретному методу Bot API.

Таблица основных операций Telegram Node в N8n

Операция (Operation)	Описание	Ключевые поля для ввода
Send Message	Отправка текстового сообщения. Поддерживает разметку Markdown или HTML.	Chat ID, Text, Parse Mode, Reply Markup (кнопки).
Send Photo	Отправка изображения. Файл может быть передан по URL или как бинарные данные из предыдущего узла.	Chat ID, Photo (URL/Binary), Caption.
Send Document	Отправка документа (PDF, Excel и т.д.).	Chat ID, Document (URL/Binary), Caption.
Send Audio, Video, Animation	Отправка соответствующих медиафайлов.	Chat ID, Media File, Caption, Duration, Performer и др.
Send Media Group	Отправка группы фотографий или видео в виде альбома.	Chat ID, Media Items (массив).
Edit Message Text	Редактирование текста ранее отправленного сообщения.	Chat ID, Message ID, New Text, Reply Markup.
Delete Message	Удаление сообщения в чате.	Chat ID, Message ID.
Answer Callback Query	Ответ на запрос от inline-кнопки (уведомление «всплывающее» или изменение сообщения).	Callback Query ID, Text, Show Alert.
Get Chat Member	Получение информации о участнике чата.	Chat ID, User ID.
Set Chat Title	Изменение названия группы/супергруппы.	Chat ID, Title.

Триггерные события (Telegram Trigger)

Узел «Telegram Trigger» является стартовой точкой workflow. Его настройка определяет, какие события будут активировать весь процесс.

События (Updates):
- Message: Любое сообщение, команда, фото, документ и т.д.
- Callback Query: Нажатие на inline-кнопку.
- Channel Post: Новое сообщение в канале.
- Edited Message / Edited Channel Post: Редактирование сообщения.
Режим опроса (Polling): Бот периодически опрашивает серверы Telegram на наличие новых событий. Подходит для локальной разработки и серверов без публичного домена.
Режим вебхука (Webhook): Telegram отправляет запрос на указанный вами публичный URL N8n при каждом новом событии. Более быстрый и эффективный метод для продакшена.

При использовании триггера, данные о событии (например, текст сообщения, ID чата, информация о пользователе, файлы) передаются в последующие узлы workflow как JSON-объект. К ним можно обращаться через выражения N8n, например: {{$json.message.chat.id}} для получения идентификатора чата.

Практические примеры рабочих процессов (Workflows)

Пример 1: Простая система уведомлений об ошибках

Цель: При возникновении ошибки в системе (например, падение сервера) отправить сообщение в приватный Telegram-чат администратора.

Узел «Schedule Trigger» — запускает workflow каждые 5 минут.
Узел «HTTP Request» — опрашивает статус-страницу сервера.
Узел «IF» — проверяет, вернулся ли ответ с кодом ошибки (например, не 200).
Узел «Telegram» (операция Send Message) — если условие истинно, отправляет сообщение вида «ВНИМАНИЕ! Сервер X недоступен. Код ответа: {{$json.statusCode}}». Поле Chat ID содержит числовой ID чата с администратором.

Пример 2: Чат-бот для сбора заявок

Цель: Бот принимает команду /start, запрашивает имя и email пользователя, а затем отправляет данные в Google Sheets.

Узел «Telegram Trigger» (Updates: Message) — ловит все сообщения.
Узел «IF» — проверяет, содержит ли сообщение команду /start.
- Если да: Переходит к узлу «Telegram» (Send Message) с приветствием и запросом имени.
- Если нет: Проверяет, ожидается ли ввод имени (это состояние нужно хранить, например, в переменных или отдельной базе данных).
Для хранения состояния между сообщениями можно использовать узлы «Set» для записи данных в память workflow (для простых случаев) или внешнюю базу данных, такую как SQLite или PostgreSQL, через соответствующие узлы N8n.
После сбора всех данных узел «Google Sheets» добавляет строку с контактом в таблицу.
Финальный узел «Telegram» отправляет подтверждение пользователю.

Пример 3: Автоматическое копирование постов из канала в чат

Цель: Когда в публичном канале появляется новое сообщение, автоматически переслать его в групповой чат для обсуждения.

Узел «Telegram Trigger» (Updates: Channel Post) — подключается к боту, который является администратором канала.
Узел «Telegram» (операция Forward Message) — использует данные из триггера: {{$json.channelPost.chat.id}} (исходный канал), {{$json.channelPost.message_id}} (ID сообщения) и указывает целевой Chat ID группы.

Обработка медиафайлов и бинарных данных

Telegram Node в N8n может работать с файлами двумя способами:

По URL: В поле «Photo», «Document» и т.д. можно ввести прямую публичную ссылку на файл. N8n загрузит и отправит его.
Как бинарные данные (Binary Data): Если предыдущий узел (например, «Read/Write File from Disk», «HTTP Request» для загрузки файла, или «Google Drive») выводит бинарные данные, их можно передать в Telegram Node. Для этого в поле ввода файла необходимо использовать выражение, выбирающее бинарные данные, например: {{$binary}} или указать конкретное свойство.

Безопасность и лучшие практики

Хранение токена: Никогда не встраивайте токен бота напрямую в узлы. Всегда используйте систему Credentials N8n.
Chat ID: Идентификатор чата является конфиденциальной информацией. Храните его в credentials или переменных окружения, а не в открытом виде в workflow.
Валидация ввода: При создании бота, взаимодействующего с пользователями, всегда проверяйте входящие данные. Не доверяйте данным из сообщений без проверки.
Ограничения Telegram API: Соблюдайте лимиты API: не более 30 сообщений в секунду для одного бота и не более 20 сообщений в минуту в один чат.
Использование вебхуков: При настройке вебхука на продакшн-сервере убедитесь, что ваш инстанс N8n использует HTTPS (Telegram требует безопасное соединение для вебхуков).

Интеграция с другими узлами N8n

Мощь Telegram Node раскрывается в полной мере при интеграции с другими узлами экосистемы N8n:

Базы данных (PostgreSQL, MySQL): Для сохранения пользовательских данных, логов, состояний сессий.
Облачные хранилища (Google Drive, S3): Для сохранения файлов, полученных через бота.
Электронная почта (SMTP, Gmail): Для отправки уведомлений из Telegram на email и наоборот.
Вебхуки (Webhook, HTTP Request): Для передачи данных из Telegram во внешние системы или для запросов к внешним API по команде из чата.
Логирование (Sentry, Discord): Для отправки ошибок и логов выполнения workflow в Telegram-чат разработчиков.

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

Как получить Chat ID?

Есть несколько способов:
1. Отправьте сообщение боту из нужного чата (или добавьте его в группу). Затем откройте в браузере URL: https://api.telegram.org/bot[ВАШ_ТОКЕН]/getUpdates. В ответе JSON найдите объект «chat» и поле «id». Для групп он будет отрицательным числом.
2. Используйте специальных ботов, таких как @getidsbot.
3. Внутри workflow N8n: используйте узел Telegram Trigger. При отправке сообщения в чат, Chat ID будет доступен в выходных данных узла как {{$json.message.chat.id}}.

Почему бот не видит сообщения в группе?

Убедитесь, что:
— Бот добавлен в группу.
— Боту были выданы права администратора (для чтения всех сообщений, если группа является супергруппой с настройками приватности).
— В триггере «Telegram Trigger» выбран правильный тип события («Message»).

В чем разница между Polling и Webhook?

Polling (опрос): Ваш сервер N8n периодически (каждые несколько секунд) сам запрашивает у серверов Telegram новые события. Проще в настройке, не требует публичного домена и HTTPS, но создает небольшую задержку и нагрузку.
Webhook (вебхук): Telegram сам отправляет HTTP-запрос на указанный вами URL вашего сервера N8n мгновенно при наступлении события. Требует публичного домена с HTTPS (для локального тестирования можно использовать ngrok или аналоги). Более быстрый и эффективный метод для продакшена.

Как отправить сообщение с клавиатурой (кнопками)?

В узле «Telegram» (Send Message) используйте поле «Reply Markup». Выберите тип «Inline Keyboard» или «Reply Keyboard». Данные должны быть переданы в формате JSON. Например, для inline-кнопки:
[ { "text": "Кнопка 1", "callback_data": "action_1" } ]
Для обработки нажатия на такую кнопку необходимо использовать триггер «Telegram Trigger» с событием «Callback Query».

Как отправить файл с моего компьютера?

N8n не имеет прямого доступа к локальной файловой системе сервера в визуальном редакторе. Необходимо:
1. Либо предварительно загрузить файл на публично доступный URL и указать этот URL в узле.
2. Либо использовать узел «Read/Write Files from Disk» (требует настройки файловой системы на сервере N8n) для чтения файла в бинарные данные, а затем передать эти данные в Telegram Node.

Можно ли использовать одного бота в нескольких разных workflow?

Да, можно. Создайте один ресурс (Credential) с токеном этого бота и используйте его в нескольких узлах Telegram Trigger и Telegram в разных workflow. Однако будьте осторожны: если вы настроите несколько триггеров на вебхук для одного бота, последний установленный вебхук перезапишет предыдущий. Для одного бота в рамках одного инстанса N8n следует использовать только один триггер на вебхуке или несколько на polling.

Как обрабатывать несколько типов сообщений (текст, фото, документ) в одном боте?

Используйте узел «Telegram Trigger» с событием «Message». На выходе он будет выдавать все типы сообщений. Далее, с помощью узла «IF» или «Switch», вы можете разветвить workflow, проверяя наличие определенных полей в полученных данных. Например, если существует $json.message.photo — значит, было отправлено фото; если $json.message.document — документ и т.д.