n8n Telegram Integration: Connect a Telegram Bot, Trigger Workflows and Send Messages
To connect n8n to Telegram you need one thing from Telegram: a bot token. Save it as the Access Token of a Telegram credential in n8n, then use the Telegram Trigger node to start workflows on incoming messages and the Telegram node to send messages to a chat id. The trigger works through a Bot API webhook, so your n8n instance must be reachable at a public HTTPS URL. This guide walks through the setup, the configuration self-hosted n8n needs, and the errors people hit most often.
How the n8n Telegram integration works
| Node | What it does | Bot API under the hood | Needs public HTTPS? |
|---|---|---|---|
| Telegram Trigger | Starts the workflow on an update: a message, a button press, a channel post and so on | setWebhook, then Telegram POSTs updates to n8n | Yes |
| Telegram | Sends and edits messages, sends files, answers callback queries, reads chat info | sendMessage, sendPhoto, editMessageText, answerCallbackQuery… | No, outgoing requests only |
Because the trigger uses a webhook, the Bot API rules for webhooks apply to n8n too: HTTPS only, ports 443, 80, 88 or 8443, one webhook URL per bot, and no getUpdates while the webhook is set.
Step 1: create a bot and get the token
- Open @BotFather, send
/newbot, choose a display name and a username that ends inbot. - Copy the token BotFather returns. It looks like
123456789:AAEexampleTokenReplaceWithYours. For an existing bot, open/mybots→ your bot → API Token. - Check the token before pasting it anywhere:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"
A valid token returns "ok": true with the bot's details; a wrong one returns 401 Unauthorized. You can run the same check in getMe in the Bot API Tester. Details on finding, checking and revoking tokens are in the Telegram bot token guide; if you don't have a bot yet, start with how to create a Telegram bot.
Step 2: add Telegram credentials in n8n
n8n authenticates to Telegram with the bot token only. Create a new Telegram credential and paste the token into its Access Token field. The Telegram node and the Telegram Trigger node use the same credential type, so one credential per bot is enough.
Treat the token like a password: anyone who has it controls the bot. If it leaks, revoke it in @BotFather and update the credential in n8n.
Step 3: receive updates with the n8n Telegram Trigger webhook
Add a Telegram Trigger node, select your credential and choose which updates should start the workflow. Typical choices are Message for incoming messages and Callback Query for inline button presses; * means all updates except chat member and reaction updates, which matches the Bot API default. The node can also be limited to specific chat ids or user ids, and can download attached images and files.
When you test the workflow or publish it, n8n calls setWebhook for your bot with a URL of its own instance. From then on, Telegram sends every update as an HTTPS POST to n8n. Two things follow from this:
- Test and production URLs overwrite each other. n8n uses different webhook URLs for testing in the editor and for the published workflow. Telegram stores only one URL per bot, so whichever was registered last receives the updates. Unpublish the workflow while testing, or use a separate bot for testing.
- One bot, one trigger. Two workflows, or two n8n instances, with a Telegram Trigger on the same bot keep replacing each other's webhook. Use one trigger per bot and branch inside the workflow, for example with a Switch node on the message text.
Make self-hosted n8n reachable over HTTPS
n8n Cloud already has a public HTTPS address. A self-hosted instance builds its webhook URLs from its own protocol, host and port, which behind a reverse proxy or on localhost is usually an http:// address that Telegram rejects. The fix:
- Put n8n behind a reverse proxy (nginx, Caddy, Traefik and so on) that terminates TLS with a valid certificate on port 443.
- Tell n8n its public address. Current n8n versions use
N8N_WEBHOOK_URL; the olderWEBHOOK_URLis deprecated since n8n 2.35.0 but still read, and versions before 2.30.0 only knowWEBHOOK_URL. - Set
N8N_PROXY_HOPS=1and forward theX-Forwarded-For,X-Forwarded-HostandX-Forwarded-Protoheaders from the proxy. - Enable WebSocket proxying, otherwise the editor can look stuck while it waits for a test trigger event.
- Restart n8n and re-activate the workflow so the trigger registers the new HTTPS URL.
# n8n behind a reverse proxy that serves https://n8n.example.com
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# n8n versions before 2.30.0: use WEBHOOK_URL instead
# export WEBHOOK_URL=https://n8n.example.com/
For local development, a tunnel that gives you a public HTTPS hostname works the same way: put that hostname into N8N_WEBHOOK_URL. Keep in mind that the webhook breaks whenever the tunnel address changes.
Check which webhook Telegram has for your bot
When the trigger stays silent, ask Telegram directly with getWebhookInfo. It shows the registered URL, how many updates are waiting, and the last delivery error. This script prints a short diagnosis:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"] # the same token as in the n8n credential
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: wrong token
info = data["result"]
print("Webhook URL:", info["url"] or "(none: no active Telegram Trigger)")
print("Pending updates:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
print("Problem: Telegram needs an HTTPS URL")
if "last_error_message" in info:
print("Last delivery error:", info["last_error_message"])const TOKEN = process.env.BOT_TOKEN; // the same token as in the n8n credential
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: wrong token
process.exit(1);
}
const info = data.result;
console.log("Webhook URL:", info.url || "(none: no active Telegram Trigger)");
console.log("Pending updates:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
console.log("Problem: Telegram needs an HTTPS URL");
}
if (info.last_error_message) {
console.log("Last delivery error:", info.last_error_message);
}Save the JavaScript version as check.mjs and run it with Node.js 18 or newer. Read the result like this: a URL from another service means something else took over the bot's webhook; a growing pending_update_count together with a last_error_message means Telegram can't reach n8n or n8n answers with an error. Without code, use getWebhookInfo in the Bot API Tester.
Step 4: send Telegram messages from n8n
Add a Telegram node, choose the Message resource and the Send Message operation, select the credential and fill in two fields:
- Chat ID: a numeric id such as
123456789, or@channelusernamefor a public channel. In a workflow that starts with the Telegram Trigger, map it with an expression to$json.message.chat.idso the bot replies in the same chat. - Text: up to 4096 characters after entity parsing, the
sendMessagelimit.
Two defaults surprise people. The node appends the line This message was sent automatically with n8n; switch off Append n8n Attribution under additional fields to remove it. And the node's parse mode defaults to HTML, so escape <, > and & in dynamic text as <, > and &, or Telegram rejects the message with a can't parse entities error.
Before wiring a chat id into a workflow, you can confirm it works with one request in sendMessage in the Bot API Tester. To post in a channel, add the bot as a channel administrator first. Telegram allows about 30 messages per second in bulk and about one per second in a single chat, so throttle broadcast loops; see Telegram Bot API limits.
Finding the chat id
The easiest source is the trigger itself: run the workflow, message the bot, and read message.chat.id in the trigger output. Users have positive ids, groups negative ones, and supergroups and channels look like -1001234567890. If you prefer getUpdates, call it before any Telegram Trigger for this bot is active; while the webhook is set it fails with 409 Conflict. All methods, including groups, channels and forum topics, are in how to get a Telegram chat id.
Troubleshooting n8n Telegram errors
| Symptom | Cause | Fix |
|---|---|---|
Bad Request: bad webhook: An HTTPS URL must be provided for webhook | n8n registered an http:// URL: localhost, or a proxy without TLS | Terminate TLS in the proxy and set N8N_WEBHOOK_URL (or WEBHOOK_URL) to the HTTPS address |
| Bad webhook error about the port | The public URL uses a port other than 443, 80, 88 or 8443 | Expose n8n on 443 through the proxy |
409 Conflict from getUpdates | A Telegram Trigger keeps a webhook registered | Deactivate the workflow and call deleteWebhook, or take chat ids from the trigger |
| Workflow works only in testing or only when published | Test and production webhook URLs replace each other | Unpublish while testing or use a separate test bot |
| Trigger stopped after another workflow was activated | A second trigger, or another service, called setWebhook with the same token | One trigger per bot; check the URL with getWebhookInfo |
| Editor stuck “waiting for trigger event” | Reverse proxy without WebSocket support | Enable WebSocket proxying, then reopen the workflow |
| No updates for group messages | Privacy mode: in groups the bot gets only commands for it, replies to it and service messages | Turn privacy off with /setprivacy or make the bot an admin |
401 Unauthorized | Wrong or revoked token in the credential | Check it with getMe and paste the current token |
400 Bad Request: chat not found when sending | Wrong chat id, or a chat the bot can't access: the user never started it, or the bot isn't in the group | Re-check the id; have the user send /start or add the bot to the group |
To start from a clean state, deactivate the workflow, call deleteWebhook, check that getWebhookInfo shows an empty url, then activate the workflow again so n8n registers its URL afresh. For webhook mechanics in general (secret tokens, retries, certificates), see the Telegram bot webhook guide.
Frequently asked questions
How do I connect Telegram to n8n?
Create a bot with @BotFather, copy its token and save it as the Access Token of a Telegram credential in n8n. Use the Telegram Trigger node to receive messages and the Telegram node to send them; both nodes use the same credential.
Why does the n8n Telegram Trigger say “An HTTPS URL must be provided for webhook”?
The trigger registers a webhook with setWebhook, and Telegram accepts only public HTTPS URLs. If n8n runs on http://localhost or behind a proxy without TLS, set the public HTTPS address of your instance in N8N_WEBHOOK_URL (WEBHOOK_URL on older versions) and terminate TLS in the reverse proxy.
Can two n8n workflows use the same Telegram bot trigger?
Not reliably. A bot has exactly one webhook URL, so each activation overwrites the previous one and only the last workflow receives updates. Use one trigger per bot, or route inside a single workflow, or create a separate bot.
Why does getUpdates return 409 Conflict after I set up n8n?
An active Telegram Trigger keeps a webhook registered for the bot, and getUpdates doesn't work while a webhook is set. Deactivate the workflow and call deleteWebhook if you need polling, or read chat ids from the trigger's output instead.
Do I need a public HTTPS URL just to send Telegram messages from n8n?
No. The Telegram node only makes outgoing requests to api.telegram.org, so sending works from a local n8n instance. Public HTTPS is needed only to receive updates with the Telegram Trigger.
Where do I find the chat id for the n8n Telegram node?
Take it from the trigger output (message.chat.id), or message the bot and call getUpdates before the trigger is active. Public channels also accept @channelusername.
Related guides
How to Create a Telegram Bot: Step by Step with BotFather and Python
How to create a Telegram bot step by step: register it with @BotFather, get the token, test it with getMe and send a first message with curl or Python.
How to Deploy a Telegram Bot: VPS, Docker and Serverless Hosting
How to deploy a Telegram bot: polling vs webhook, a systemd service on a VPS, Docker, Cloudflare Workers with secret_token, plus a launch checklist.
Telegram Bot API 10.0–10.5: Bot Settings, Widgets, Rich Messages, Ephemeral Messages, Guest Mode and More
What's new in Telegram Bot API 10.0–10.5: setMySettings and BotFullInfo, HTML widgets, rich and ephemeral messages, guest mode, with JSON examples.
Telegram Bot API Errors: What Each Error Means and How to Fix It
Telegram Bot API errors explained: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causes, fixes and handling code.
Telegram Bot API Limits: Rate Limits, 429 Errors, File Sizes and Message Length
Telegram Bot API rate limits explained: 30 msg/s, 1 msg/s per chat, 20/min in groups, handling 429 retry_after, plus file size and message length limits.
Telegram Bot Commands: setMyCommands, Command Scopes and /start Deep Links
Set up Telegram bot commands: @BotFather /setcommands, setMyCommands with scopes and languages, /start deep link parameters and /cmd@bot in groups.
Telegram Bot Keyboards: Inline Keyboard, Callback Buttons and Reply Keyboard
Add Telegram bot buttons: inline keyboard with callback_data, answerCallbackQuery, editing the message after a press, reply keyboard and ForceReply.
How to Send a Message with the Telegram Bot API (sendMessage)
Telegram Bot API send message guide: sendMessage with curl, Python and JavaScript, HTML and MarkdownV2 formatting, inline buttons and error fixes.
Telegram Bot Token: How to Get It, Find It Again, Check It and Keep It Safe
Telegram bot token guide: get one from @BotFather, find the token of an existing bot, check it with getMe, revoke a leaked token and store it safely.
How to Set Up a Telegram Bot Webhook: setWebhook, Secret Token and Troubleshooting
Set up a Telegram bot webhook: setWebhook URL requirements, secret_token header check, getWebhookInfo debugging, deleteWebhook and fixes for n8n.
How to Get a Telegram Chat ID for a User, Group, Channel or Topic
How to get a Telegram chat ID for a user, group, supergroup, channel or forum topic with getUpdates, plus fixes for an empty result and 409 Conflict.
Telegram Inline Bot: How to Enable Inline Mode and Answer Inline Queries
Build a Telegram inline bot: enable inline mode with @BotFather or setMySettings, handle inline_query updates and reply with answerInlineQuery.
Telegram Stars Payments for Bots: Invoices, Pre-Checkout, Refunds and Subscriptions
Accept Telegram Stars payments in your bot: sendInvoice with XTR, pre_checkout_query, successful_payment, refunds, subscriptions, Python/JS code.
Telegram Test Server: How to Test a Bot in the Telegram Test Environment
Use the Telegram test server for bots: log in to the test environment, create a test bot, call the Bot API via /test/ and switch our tester to TEST.
Telegram Widgets for Your Website: Login Widget, Post Embed, Discussion and Share Button
Add Telegram to your website: the new Telegram Login (OIDC), the legacy Login Widget with hash check code, post embeds, comments and a share button.
TelegramWidget JavaScript API: Reference, Events, Error Codes and Limits
TelegramWidget JavaScript API reference: properties, request(), events, error codes, CSS variables, widget_query and answerWidgetQuery, plus every limit.
Telegram Widget Examples: Complete HTML and Python Bot Code
Working Telegram widget examples with full code: a static order card, a counter with widget_query requests, a shared live poll and a local preview stub.
Telegram Widgets: Interactive HTML Inside Bot Messages
Telegram widgets (Bot API 10.4): what they are, how sendWidget, chat_data and public_data work, where they run today and how they differ from Mini Apps.
How to Test a Telegram Mini App: From Browser Mock to Real Telegram
Test a Telegram Mini App step by step: browser mock mode, localhost via HTTPS tunnel, test environment, DevTools per platform, initData validation.