Telegram Bot API

Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений

· 8 мин чтения

Чтобы подключить n8n к Telegram, от Telegram нужен только токен бота. Сохраните его в поле Access Token учётных данных Telegram в n8n, а дальше используйте узел Telegram Trigger, чтобы запускать воркфлоу по входящим сообщениям, и узел Telegram, чтобы отправлять сообщения по chat id. Триггер работает через вебхук Bot API, поэтому n8n должен быть доступен по публичному HTTPS-адресу. Ниже — пошаговая настройка, что нужно self-hosted n8n и как исправить самые частые ошибки.

Как устроена интеграция n8n и Telegram

УзелЧто делаетЧто вызывает в Bot APIНужен публичный HTTPS?
Telegram TriggerЗапускает воркфлоу по апдейту: сообщению, нажатию кнопки, посту в канале и т. д.setWebhook, после чего Telegram сам шлёт апдейты в n8nДа
TelegramОтправляет и редактирует сообщения, шлёт файлы, отвечает на callback-запросы, читает данные чатаsendMessage, sendPhoto, editMessageText, answerCallbackQuery…Нет, только исходящие запросы

Раз триггер использует вебхук, на n8n распространяются те же правила Bot API: только HTTPS, порты 443, 80, 88 или 8443, один URL вебхука на бота и никакого getUpdates, пока вебхук установлен.

Шаг 1: создать бота и получить токен

  1. Откройте @BotFather, отправьте /newbot, придумайте отображаемое имя и username, который заканчивается на bot.
  2. Скопируйте токен из ответа BotFather. Он выглядит так: 123456789:AAEexampleTokenReplaceWithYours. Для существующего бота: /mybots → ваш бот → API Token.
  3. Проверьте токен, прежде чем куда-либо вставлять:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

Рабочий токен вернёт "ok": true с данными бота, неверный — 401 Unauthorized. То же самое можно проверить в getMe в Bot API Tester. Как найти, проверить и отозвать токен, подробно описано в гайде о токене бота; если бота ещё нет, начните с инструкции по созданию бота в Telegram.

Шаг 2: добавить учётные данные Telegram в n8n

n8n авторизуется в Telegram только по токену бота. Создайте новые учётные данные (credential) типа Telegram и вставьте токен в поле Access Token. Узлы Telegram и Telegram Trigger используют один и тот же тип учётных данных, так что на одного бота достаточно одной записи.

Обращайтесь с токеном как с паролем: у кого токен, тот управляет ботом. Если он утёк, отзовите его в @BotFather и обновите учётные данные в n8n.

Шаг 3: принимать апдейты через вебхук n8n Telegram Trigger

Добавьте узел Telegram Trigger, выберите учётные данные и отметьте, какие апдейты должны запускать воркфлоу. Обычно это Message для входящих сообщений и Callback Query для нажатий inline-кнопок; * означает все апдейты, кроме изменений участников чата и реакций, — как и по умолчанию в Bot API. Узел также умеет ограничиваться конкретными chat id или user id и скачивать вложенные изображения и файлы.

Когда вы тестируете воркфлоу или публикуете его, n8n вызывает для бота setWebhook с адресом своего инстанса. С этого момента Telegram отправляет каждый апдейт в n8n HTTPS-запросом POST. Из этого следуют два важных момента:

Как открыть self-hosted n8n по HTTPS

У n8n Cloud публичный HTTPS-адрес уже есть. Self-hosted инстанс собирает URL вебхуков из собственных протокола, хоста и порта, и за обратным прокси или на localhost это обычно адрес http://, который Telegram отклоняет. Что сделать:

  1. Поставьте n8n за обратный прокси (nginx, Caddy, Traefik и т. п.), который завершает TLS с действительным сертификатом на порту 443.
  2. Сообщите n8n его публичный адрес. Актуальные версии n8n используют N8N_WEBHOOK_URL; старая WEBHOOK_URL объявлена устаревшей с n8n 2.35.0, но пока читается, а версии до 2.30.0 знают только WEBHOOK_URL.
  3. Задайте N8N_PROXY_HOPS=1 и пробрасывайте с прокси заголовки X-Forwarded-For, X-Forwarded-Host и X-Forwarded-Proto.
  4. Включите проксирование WebSocket, иначе редактор может «зависнуть» в ожидании тестового события триггера.
  5. Перезапустите n8n и заново активируйте воркфлоу, чтобы триггер зарегистрировал новый HTTPS-адрес.
# n8n за обратным прокси, который обслуживает https://n8n.example.com
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# версии n8n до 2.30.0: используйте WEBHOOK_URL
# export WEBHOOK_URL=https://n8n.example.com/

Для локальной разработки подойдёт туннель с публичным HTTPS-хостом: укажите этот хост в N8N_WEBHOOK_URL. Учтите, что при смене адреса туннеля вебхук перестаёт работать.

Проверить, какой вебхук Telegram хранит для бота

Если триггер молчит, спросите Telegram напрямую методом getWebhookInfo: он покажет зарегистрированный URL, число апдейтов в очереди и последнюю ошибку доставки. Этот скрипт выводит краткую диагностику:

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]  # тот же токен, что в учётных данных n8n
API = f"https://api.telegram.org/bot{TOKEN}"

data = requests.get(f"{API}/getWebhookInfo", timeout=10).json()
if not data["ok"]:
    raise SystemExit(f"{data['error_code']} {data['description']}")  # 401: неверный токен

info = data["result"]
print("URL вебхука:", info["url"] or "(нет: Telegram Trigger не активен)")
print("Апдейтов в очереди:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
    print("Проблема: Telegram нужен HTTPS-адрес")
if "last_error_message" in info:
    print("Последняя ошибка доставки:", info["last_error_message"])
const TOKEN = process.env.BOT_TOKEN; // тот же токен, что в учётных данных n8n
const API = `https://api.telegram.org/bot${TOKEN}`;

const data = await (await fetch(`${API}/getWebhookInfo`)).json();
if (!data.ok) {
  console.error(`${data.error_code} ${data.description}`); // 401: неверный токен
  process.exit(1);
}

const info = data.result;
console.log("URL вебхука:", info.url || "(нет: Telegram Trigger не активен)");
console.log("Апдейтов в очереди:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
  console.log("Проблема: Telegram нужен HTTPS-адрес");
}
if (info.last_error_message) {
  console.log("Последняя ошибка доставки:", info.last_error_message);
}

JavaScript-версию сохраните как check.mjs и запускайте в Node.js 18 или новее. Как читать результат: URL другого сервиса значит, что вебхук бота перехватил кто-то ещё; растущий pending_update_count вместе с last_error_message — что Telegram не может достучаться до n8n или n8n отвечает ошибкой. Без кода то же самое покажет getWebhookInfo в Bot API Tester.

Шаг 4: отправлять сообщения в Telegram из n8n

Добавьте узел Telegram, выберите ресурс Message и операцию Send Message, укажите учётные данные и заполните два поля:

Два значения по умолчанию часто удивляют. Узел дописывает в конец строку This message was sent automatically with n8n — чтобы её убрать, выключите Append n8n Attribution в дополнительных полях. А режим разметки по умолчанию — HTML, поэтому в динамическом тексте экранируйте <, > и & как &lt;, &gt; и &amp;, иначе Telegram отклонит сообщение с ошибкой can't parse entities.

Прежде чем вписывать chat id в воркфлоу, проверьте его одним запросом в sendMessage в Bot API Tester. Чтобы публиковать в канал, сначала добавьте бота администратором канала. Telegram допускает около 30 сообщений в секунду при массовой рассылке и примерно одно в секунду в один чат, так что притормаживайте циклы рассылки; подробнее — в гайде о лимитах Telegram Bot API.

Как узнать chat id

Проще всего взять его из самого триггера: запустите воркфлоу, напишите боту и посмотрите message.chat.id в выводе триггера. У пользователей id положительные, у групп отрицательные, а у супергрупп и каналов выглядят как -1001234567890. Если удобнее getUpdates, вызывайте его до активации Telegram Trigger для этого бота: пока вебхук установлен, метод падает с 409 Conflict. Все способы, включая группы, каналы и темы форумов, — в гайде как узнать chat id в Telegram.

Частые ошибки n8n с Telegram

СимптомПричинаРешение
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n зарегистрировал адрес http://: localhost или прокси без TLSНастройте TLS на прокси и укажите HTTPS-адрес в N8N_WEBHOOK_URL (или WEBHOOK_URL)
Ошибка bad webhook из-за портаПубличный URL использует порт, отличный от 443, 80, 88 и 8443Откройте n8n через прокси на 443
409 Conflict от getUpdatesTelegram Trigger держит зарегистрированный вебхукДеактивируйте воркфлоу и вызовите deleteWebhook либо берите chat id из триггера
Воркфлоу работает только в тесте или только после публикацииТестовый и рабочий URL вебхука вытесняют друг другаСнимайте с публикации на время тестов или заведите тестового бота
Триггер замолчал после активации другого воркфлоуВторой триггер или другой сервис вызвал setWebhook с тем же токеномОдин триггер на бота; проверьте URL через getWebhookInfo
Редактор висит в ожидании события триггераОбратный прокси без поддержки WebSocketВключите проксирование WebSocket и переоткройте воркфлоу
Не приходят сообщения из группыРежим приватности: в группах бот получает только адресованные ему команды, ответы на свои сообщения и служебные сообщенияОтключите его через /setprivacy или сделайте бота администратором
401 UnauthorizedВ учётных данных неверный или отозванный токенПроверьте его через getMe и вставьте актуальный
400 Bad Request: chat not found при отправкеНеверный chat id или чат, к которому у бота нет доступа: пользователь не запускал бота или бота нет в группеПерепроверьте id; попросите пользователя отправить /start или добавьте бота в группу

Чтобы начать с чистого листа, деактивируйте воркфлоу, вызовите deleteWebhook, убедитесь, что getWebhookInfo показывает пустой url, и снова активируйте воркфлоу — n8n заново зарегистрирует свой адрес. Общие принципы работы вебхуков (secret token, повторные доставки, сертификаты) разобраны в гайде по вебхуку телеграм-бота.

Частые вопросы

Как подключить Telegram к n8n?

Создайте бота в @BotFather, скопируйте токен и сохраните его в поле Access Token учётных данных Telegram в n8n. Для приёма сообщений используйте узел Telegram Trigger, для отправки — узел Telegram; оба работают с одними и теми же учётными данными.

Почему n8n Telegram Trigger пишет «An HTTPS URL must be provided for webhook»?

Триггер регистрирует вебхук через setWebhook, а Telegram принимает только публичные HTTPS-адреса. Если n8n работает на http://localhost или за прокси без TLS, укажите публичный HTTPS-адрес инстанса в N8N_WEBHOOK_URL (в старых версиях — WEBHOOK_URL) и настройте TLS на обратном прокси.

Можно ли повесить Telegram Trigger на одного бота в двух воркфлоу?

Надёжно — нет. У бота ровно один URL вебхука, поэтому каждая активация перезаписывает предыдущую, и апдейты получает только последний воркфлоу. Оставьте один триггер на бота и ветвите логику внутри воркфлоу либо заведите отдельного бота.

Почему после настройки n8n getUpdates возвращает 409 Conflict?

Активный Telegram Trigger держит у бота зарегистрированный вебхук, а пока вебхук установлен, getUpdates не работает. Если нужен polling, деактивируйте воркфлоу и вызовите deleteWebhook; chat id можно взять и из вывода триггера.

Нужен ли публичный HTTPS, чтобы просто отправлять сообщения из n8n?

Нет. Узел Telegram только делает исходящие запросы к api.telegram.org, поэтому отправка работает и с локального n8n. Публичный HTTPS нужен лишь для приёма апдейтов через Telegram Trigger.

Где взять chat id для узла Telegram в n8n?

Из вывода триггера (message.chat.id) или через getUpdates, пока триггер ещё не активен: напишите боту и вызовите метод. Для публичных каналов подойдёт @channelusername.

Как создать бота в Телеграм: от @BotFather до первого сообщения

Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.

Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг

Как задеплоить Telegram-бота: polling или вебхук, сервис systemd на VPS, Docker, Cloudflare Workers с secret_token и чек-лист перед запуском.

Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим

Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.

Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить

Ошибки Telegram Bot API с решениями: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 и retry_after. Таблица причин и код обработки.

Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов

Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.

Команды Telegram-бота: setMyCommands, области видимости и deep link для /start

Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.

Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура

Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.

Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки

Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.

Токен бота Telegram: как получить, где найти, как проверить и отозвать

Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.

Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление

Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.

Как узнать chat id в Telegram: пользователь, группа, канал и тема форума

Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.

Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы

Как сделать инлайн-бота Telegram: включить inline mode через @BotFather или setMySettings, обработать inline_query и ответить через answerInlineQuery.

Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки

Приём оплаты в Telegram Stars в боте: sendInvoice с XTR, pre_checkout_query, successful_payment, возвраты, подписки и пример на Python и JS.

Тестовый сервер Telegram: как тестировать бота в тестовом окружении

Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.

Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»

Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».

TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты

Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.

Примеры виджетов Telegram: готовый HTML и код бота на Python

Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.

Виджеты Telegram: интерактивный HTML прямо в сообщениях бота

Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.

Тестирование Telegram Mini App: от браузера до отладки на телефоне

Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.