Telegram Bot API

n8n Telegram Integration: Connect a Telegram Bot, Trigger Workflows and Send Messages

· 8 min read

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

NodeWhat it doesBot API under the hoodNeeds public HTTPS?
Telegram TriggerStarts the workflow on an update: a message, a button press, a channel post and so onsetWebhook, then Telegram POSTs updates to n8nYes
TelegramSends and edits messages, sends files, answers callback queries, reads chat infosendMessage, 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

  1. Open @BotFather, send /newbot, choose a display name and a username that ends in bot.
  2. Copy the token BotFather returns. It looks like 123456789:AAEexampleTokenReplaceWithYours. For an existing bot, open /mybots → your bot → API Token.
  3. 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:

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:

  1. Put n8n behind a reverse proxy (nginx, Caddy, Traefik and so on) that terminates TLS with a valid certificate on port 443.
  2. Tell n8n its public address. Current n8n versions use N8N_WEBHOOK_URL; the older WEBHOOK_URL is deprecated since n8n 2.35.0 but still read, and versions before 2.30.0 only know WEBHOOK_URL.
  3. Set N8N_PROXY_HOPS=1 and forward the X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto headers from the proxy.
  4. Enable WebSocket proxying, otherwise the editor can look stuck while it waits for a test trigger event.
  5. 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:

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 &lt;, &gt; and &amp;, 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

SymptomCauseFix
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n registered an http:// URL: localhost, or a proxy without TLSTerminate TLS in the proxy and set N8N_WEBHOOK_URL (or WEBHOOK_URL) to the HTTPS address
Bad webhook error about the portThe public URL uses a port other than 443, 80, 88 or 8443Expose n8n on 443 through the proxy
409 Conflict from getUpdatesA Telegram Trigger keeps a webhook registeredDeactivate the workflow and call deleteWebhook, or take chat ids from the trigger
Workflow works only in testing or only when publishedTest and production webhook URLs replace each otherUnpublish while testing or use a separate test bot
Trigger stopped after another workflow was activatedA second trigger, or another service, called setWebhook with the same tokenOne trigger per bot; check the URL with getWebhookInfo
Editor stuck “waiting for trigger event”Reverse proxy without WebSocket supportEnable WebSocket proxying, then reopen the workflow
No updates for group messagesPrivacy mode: in groups the bot gets only commands for it, replies to it and service messagesTurn privacy off with /setprivacy or make the bot an admin
401 UnauthorizedWrong or revoked token in the credentialCheck it with getMe and paste the current token
400 Bad Request: chat not found when sendingWrong chat id, or a chat the bot can't access: the user never started it, or the bot isn't in the groupRe-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.

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.