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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: 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.