Пакет node-red-contrib-telegrambot не появится в палитре Node-RED, пока вы не установите его через меню Manage palette или командой npm install node-red-contrib-telegrambot в каталоге пользовательских данных — это первое, что нужно проверить, если узлы telegram receiver и telegram sender отсутствуют в редакторе. Без установленного пакета и корректного токена бота любой поток с Telegram-узлами будет выдавать ошибку конфигурации ещё на этапе развёртывания.
Связка Node-RED и Telegram-бота — один из самых популярных способов получать уведомления от систем умного дома, мониторинга серверов и любых автоматизаций. Бот может не только отправлять сообщения, но и принимать команды, что превращает мессенджер в пульт управления вашими сценариями. В этом руководстве разберём установку, регистрацию бота, настройку узлов и типичные проблемы.
Что такое node-red-contrib-telegrambot
node-red-contrib-telegrambot — это набор узлов для платформы Node-RED, реализующий взаимодействие с Telegram Bot API. Пакет добавляет в палитру узлы для приёма и отправки сообщений, обработки команд, работы с клавиатурами, файлами и событиями бота. Фактически это готовый мост между визуальными потоками Node-RED и чатами Telegram.
Архитектура проста: Node-RED подключается к серверам Telegram от имени вашего бота, используя токен, и работает в режиме опроса (polling) или через webhook. Все входящие сообщения попадают в поток как объекты msg, а исходящие формируются через узел отправителя. Отдельного сервера или белого IP для режима polling не требуется — бот сам запрашивает обновления у API.
Основные узлы пакета:
- 🤖 Telegram Receiver — принимает входящие сообщения, команды и события от пользователей.
- 📤 Telegram Sender — отправляет текст, фото, документы и клавиатуры в чат.
- ⌨️ Telegram Command — реагирует на конкретные команды вида
/startили/status. - 🔘 Telegram Reply — обрабатывает нажатия inline-кнопок и ответы на сообщения.
Установка пакета в Node-RED
Самый простой способ установки — через графический интерфейс. Откройте редактор Node-RED, перейдите в меню (три полоски справа вверху) и выберите Manage palette. На вкладке Install введите в поиск node-red-contrib-telegrambot и нажмите кнопку установки рядом с найденным пакетом. После завершения установки узлы появятся в палитре без перезапуска.
Если Node-RED работает на сервере без доступа к браузеру или установка через интерфейс недоступна, используйте командную строку. Перейдите в каталог пользовательских данных Node-RED (обычно это ~/.node-red) и выполните:
cd ~/.node-red
npm install node-red-contrib-telegrambot
После установки через npm потребуется перезапуск службы Node-RED, чтобы новые узлы загрузились. Команда перезапуска зависит от способа развёртывания: для systemd это sudo systemctl restart nodered, для Docker — пересоздание контейнера с сохранением тома данных.
⚠️ Внимание: если Node-RED запущен в Docker-контейнере, установка пакета внутри контейнера без монтирования каталога данных пропадёт при пересоздании контейнера. Устанавливайте пакеты в примонтированный том или добавляйте их в образ.
Создание бота и получение токена
Прежде чем настраивать узлы, вам нужен собственный бот. Его регистрация выполняется через официального бота @BotFather в Telegram. Откройте диалог с ним и отправьте команду /newbot. BotFather попросит указать отображаемое имя бота, а затем уникальный username, обязательно заканчивающийся на bot.
В ответ вы получите токен доступа — строку вида 123456789:AAEhBOweik6ad9r_QXMENQjcrGbqCr4K-4c. Этот токен — единственный ключ, который связывает Node-RED с вашим ботом. Сохраните его в надёжном месте: любой, кто знает токен, может управлять ботом от вашего имени.
Дополнительно через BotFather можно задать описание, аватар и список команд, которые будут отображаться в меню бота. Это удобно, если планируется несколько команд управления — пользователь увидит подсказки при вводе символа /.
⚠️ Внимание: никогда не публикуйте токен в открытом виде — в коде на GitHub, скриншотах или экспортированных потоках. Если токен скомпрометирован, перевыпустите его через BotFather командой/revokeили/token.
Настройка узлов Telegram в потоке
Перетащите узел telegram sender на рабочую область и откройте его свойства двойным кликом. Нажмите на значок карандаша рядом с полем Bot и создайте новую конфигурацию: вставьте токен, задайте имя бота и выберите режим работы — polling подходит для большинства сценариев. Сохраните конфигурацию и разверните поток кнопкой Deploy.
Для отправки сообщения нужно знать chatId — числовой идентификатор чата. Проще всего узнать его так: добавьте узел telegram receiver с той же конфигурацией бота, подключите к нему узел debug, разверните поток и напишите боту любое сообщение в Telegram. В панели отладки вы увидите объект msg.payload, где в поле chatId будет нужный идентификатор.
Минимальный поток отправки выглядит так: узел inject → узел function или change, формирующий msg.payload, → узел telegram sender. Структура сообщения для отправки:
msg.payload = {
chatId: 123456789,
type: "message",
content: "Температура превышена!"
};
return msg;
☑️ Проверка перед запуском бота
Отправка сообщений, фото и кнопок
Помимо простого текста, узел отправителя поддерживает разные типы контента. Тип задаётся в поле msg.payload.type: message для текста, photo для изображений, document для файлов. Для фото в поле content передаётся путь к файлу на диске, Buffer с данными или публичный URL изображения.
Для интерактивного управления используются inline-клавиатуры. В содержимое сообщения добавляется массив кнопок, а нажатия обрабатываются узлом telegram reply, который возвращает идентификатор нажатой кнопки. Так реализуются сценарии «включить свет / выключить свет» прямо из чата.
| Тип (type) | Что отправляет | Формат content |
|---|---|---|
| message | Текстовое сообщение | Строка с текстом |
| photo | Изображение | Путь к файлу, Buffer или URL |
| document | Файл любого типа | Путь к файлу или Buffer |
| location | Геометка | Объект с координатами |
| sticker | Стикер | Идентификатор или файл стикера |
Приём команд и обработка входящих сообщений
Узел telegram command настраивается на конкретную команду, например /status. Когда пользователь отправляет её боту, узел срабатывает и передаёт в поток объект с данными сообщения. Подключив к нему логику формирования ответа и узел отправителя, вы получите классическую схему «запрос — ответ».
Важно сохранять msg.payload.chatId из входящего сообщения и подставлять его в ответ — тогда бот ответит именно тому чату, откуда пришла команда. Если потоков обработки несколько, удобно использовать узел switch для маршрутизации по типу команды или содержимому сообщения.
Для ограничения доступа к боту проверяйте chatId или username отправителя в узле function и отсекайте чужие запросы. Telegram-боты по умолчанию видны всем, кто знает username, поэтому без фильтрации любой желающий сможет отправлять команды вашей автоматизации.
Пример фильтра по chatId в узле function
Код проверки: if (msg.payload.chatId !== 123456789) { return null; } — сообщения от других пользователей просто игнорируются и не проходят дальше по потоку. Подставьте свой реальный chatId вместо значения из примера.
Типичные ошибки и их решение
Самая частая проблема — статус узла unauthorized или ошибка 401 Unauthorized. Она означает, что токен неверен: проверьте, не скопирован ли он с лишним пробелом, не перевыпускался ли через BotFather. После смены токена обновите конфигурацию бота и сделайте полный Deploy.
Ошибка 409 Conflict возникает, когда один и тот же токен используется в двух местах одновременно — например, бот запущен и в Node-RED, и в другом скрипте. Telegram Bot API не допускает параллельного polling с одним токеном. Остановите дубликат, и ошибка исчезнет.
Если бот «молчит» и не отвечает, проверьте по порядку:
- 🔌 Есть ли у сервера с Node-RED доступ в интернет и к api.telegram.org.
- 🧩 Развёрнут ли поток после последних изменений (кнопка Deploy).
- 🆔 Совпадает ли chatId в сообщении с реальным идентификатором чата.
- 📋 Нет ли ошибок в журнале Node-RED и во вкладке debug редактора.
⚠️ Внимание: в некоторых сетях и регионах доступ к серверам Telegram может быть ограничен на уровне провайдера. В этом случае polling не заработает напрямую — потребуется настройка прокси на уровне системы или Node-RED, что выходит за рамки стандартной конфигурации пакета.
Часто задаваемые вопросы
Можно ли использовать один токен бота в нескольких потоках Node-RED?
Да, в пределах одного экземпляра Node-RED одна конфигурация бота используется несколькими узлами receiver и sender одновременно. Ограничение действует только на параллельный polling одного токена из разных приложений или разных серверов.
Чем polling отличается от webhook и что выбрать?
Polling — это периодический опрос серверов Telegram самим ботом; он работает из любой сети без белого IP и проброса портов. Webhook требует публично доступного HTTPS-адреса, куда Telegram будет отправлять обновления. Для домашней автоматизации и тестов почти всегда достаточно polling.
Как отправить сообщение в группу, а не в личный чат?
Добавьте бота в группу, затем узнайте chatId группы тем же способом — через узел receiver и debug, отправив сообщение в группу. У групповых чатов идентификатор отрицательный. Используйте его в msg.payload.chatId при отправке.
Почему бот не видит сообщения других участников в группе?
По умолчанию у ботов включён режим приватности: в группах они получают только команды и ответы на свои сообщения. Режим можно отключить через @BotFather, но после изменения настройки бота нужно удалить из группы и добавить заново, чтобы изменения вступили в силу.
Можно ли отправлять фото с камеры или графики из Node-RED?
Да — сохраните изображение в файл или сформируйте Buffer (например, график из узла графиков либо снимок, полученный по HTTP), затем передайте его в msg.payload.content с типом photo. Узел sender сам загрузит файл в Telegram.