Інтеграція n8n і Telegram: підключення бота, Telegram Trigger і надсилання повідомлень
Щоб підключити 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: створити бота й отримати токен
- Відкрийте @BotFather, надішліть
/newbot, придумайте ім'я для відображення та username, що закінчується наbot. - Скопіюйте токен із відповіді BotFather. Він має такий вигляд:
123456789:AAEexampleTokenReplaceWithYours. Для наявного бота:/mybots→ ваш бот → API Token. - Перевірте токен, перш ніж кудись його вставляти:
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. Звідси два важливі наслідки:
- Тестовий і робочий URL перезаписують один одного. Для тестування в редакторі та для опублікованого воркфлоу n8n використовує різні адреси вебхука. Telegram зберігає один URL на бота, тому апдейти отримує той, що зареєстрований останнім. На час тестів знімайте воркфлоу з публікації або створіть окремого тестового бота.
- Один бот — один тригер. Два воркфлоу чи два інстанси n8n з Telegram Trigger на одному боті постійно підміняють вебхук одне одного. Тримайте один тригер на бота й розгалужуйте логіку всередині воркфлоу, наприклад вузлом Switch за текстом повідомлення.
Як відкрити self-hosted n8n через HTTPS
У n8n Cloud публічна HTTPS-адреса вже є. Self-hosted інстанс складає URL вебхуків із власних протоколу, хоста й порту, і за зворотним проксі чи на localhost це зазвичай адреса http://, яку Telegram відхиляє. Що зробити:
- Поставте n8n за зворотний проксі (nginx, Caddy, Traefik тощо), який завершує TLS з чинним сертифікатом на порту 443.
- Повідомте n8n його публічну адресу. Актуальні версії n8n використовують
N8N_WEBHOOK_URL; стараWEBHOOK_URLзастаріла з n8n 2.35.0, але ще зчитується, а версії до 2.30.0 знають лишеWEBHOOK_URL. - Задайте
N8N_PROXY_HOPS=1і передавайте з проксі заголовкиX-Forwarded-For,X-Forwarded-HostтаX-Forwarded-Proto. - Увімкніть проксіювання WebSocket, інакше редактор може «зависнути» в очікуванні тестової події тригера.
- Перезапустіть 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, вкажіть облікові дані й заповніть два поля:
- Chat ID — числовий id на кшталт
123456789або@channelusernameдля публічного каналу. Якщо воркфлоу починається з Telegram Trigger, підставте виразом$json.message.chat.id, щоб бот відповідав у той самий чат. - Text — до 4096 символів після розбору сутностей, це ліміт
sendMessage.
Два значення за замовчуванням часто дивують. Вузол дописує в кінець рядок This message was sent automatically with n8n — щоб його прибрати, вимкніть Append n8n Attribution у додаткових полях. А режим розмітки за замовчуванням — HTML, тому в динамічному тексті екрануйте <, > і & як <, > і &, інакше 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 webhook | n8n зареєстрував адресу http://: localhost або проксі без TLS | Налаштуйте TLS на проксі й вкажіть HTTPS-адресу в N8N_WEBHOOK_URL (або WEBHOOK_URL) |
| Помилка bad webhook через порт | Публічний URL використовує порт, відмінний від 443, 80, 88 і 8443 | Відкрийте n8n через проксі на 443 |
409 Conflict від getUpdates | Telegram 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через 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.