n8n Telegram 集成教程:连接机器人、触发工作流并发送消息
把 n8n 接入 Telegram,从 Telegram 那边只需要一样东西:机器人 Token(bot token)。在 n8n 中把它保存为 Telegram 凭据的 Access Token,然后用 Telegram Trigger 节点在收到消息时启动工作流,用 Telegram 节点向指定 chat id 发送消息。触发器基于 Bot API 的 Webhook 工作,所以你的 n8n 实例必须能通过公网 HTTPS URL 访问。本文介绍完整的配置步骤、自托管 n8n 需要的设置,以及最常遇到的报错。
n8n Telegram 集成的工作原理
| 节点 | 作用 | 底层调用的 Bot API | 需要公网 HTTPS? |
|---|---|---|---|
| Telegram Trigger | 收到更新时启动工作流:消息、按钮点击、频道帖子等 | 先调用 setWebhook,之后 Telegram 把更新 POST 到 n8n | 需要 |
| Telegram | 发送和编辑消息、发送文件、响应按钮回调、读取聊天信息 | sendMessage、sendPhoto、editMessageText、answerCallbackQuery…… | 不需要,只有出站请求 |
由于触发器使用 Webhook,Bot API 对 Webhook 的规则同样适用于 n8n:只支持 HTTPS,端口只能是 443、80、88 或 8443,一个机器人只有一个 Webhook URL,并且设置了 Webhook 时不能使用 getUpdates。
第 1 步:创建机器人并获取 Token
- 打开 @BotFather,发送
/newbot,设置显示名称和以bot结尾的用户名。 - 复制 BotFather 返回的 Token,格式类似
123456789:AAEexampleTokenReplaceWithYours。已有的机器人可以通过/mybots→ 选择机器人 → API Token 查看。 - 在粘贴到任何地方之前,先检查 Token:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"
Token 有效时返回 "ok": true 和机器人信息;无效时返回 401 Unauthorized。也可以在 Bot API Tester 的 getMe 中做同样的检查。查找、检查和撤销 Token 的详细方法见 Telegram Bot Token 获取与管理教程;还没有机器人的话,请先阅读创建 Telegram 机器人教程。
第 2 步:在 n8n 中添加 Telegram 凭据
n8n 只用机器人 Token 向 Telegram 认证。新建一个 Telegram 凭据,把 Token 粘贴到 Access Token 字段。Telegram 节点和 Telegram Trigger 节点使用同一种凭据类型,所以每个机器人只需一个凭据。
请像对待密码一样对待 Token:谁拿到它,谁就能控制机器人。一旦泄露,立即在 @BotFather 中撤销,并更新 n8n 中的凭据。
第 3 步:用 n8n Telegram Trigger 的 Webhook 接收更新
添加一个 Telegram Trigger 节点,选择凭据,再选择哪些更新会启动工作流。常见的选择是 Message(收到消息)和 Callback Query(点击内联按钮);* 表示除聊天成员和表情回应之外的所有更新,与 Bot API 的默认行为一致。该节点还可以限定特定的 chat id 或 user id,并能下载消息中附带的图片和文件。
测试或发布工作流时,n8n 会以自己实例的 URL 为你的机器人调用 setWebhook。此后 Telegram 会把每个更新以 HTTPS POST 的形式发给 n8n。由此带来两点影响:
- 测试 URL 和生产 URL 会互相覆盖。n8n 在编辑器中测试和发布后的工作流使用不同的 Webhook URL,而 Telegram 每个机器人只保存一个 URL,最后注册的那个才能收到更新。测试时请先取消发布工作流,或者用单独的机器人测试。
- 一个机器人,一个触发器。两个工作流或两个 n8n 实例在同一个机器人上使用 Telegram Trigger,会不断替换对方的 Webhook。请每个机器人只用一个触发器,在工作流内部分支处理,例如用 Switch 节点按消息文本分流。
让自托管 n8n 可以通过 HTTPS 访问
n8n Cloud 自带公网 HTTPS 地址。自托管实例则根据自身的协议、主机名和端口生成 Webhook URL,在反向代理后面或 localhost 上,这通常是一个会被 Telegram 拒绝的 http:// 地址。解决方法:
- 把 n8n 放在反向代理(nginx、Caddy、Traefik 等)后面,由代理在 443 端口用有效证书终止 TLS。
- 告诉 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 URL。
# 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。注意,隧道地址一变,Webhook 就会失效。
查看 Telegram 为机器人登记的 Webhook
触发器没有反应时,直接用 getWebhookInfo 问 Telegram。它会显示已注册的 URL、等待推送的更新数量和最近一次推送错误。下面的脚本会输出简短的诊断结果:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"] # 与 n8n 凭据中相同的 Token
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:Token 错误
info = data["result"]
print("Webhook URL:", info["url"] or "(无:没有激活的 Telegram Trigger)")
print("待推送更新:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
print("问题:Telegram 要求使用 HTTPS URL")
if "last_error_message" in info:
print("最近一次推送错误:", info["last_error_message"])const TOKEN = process.env.BOT_TOKEN; // 与 n8n 凭据中相同的 Token
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:Token 错误
process.exit(1);
}
const info = data.result;
console.log("Webhook URL:", info.url || "(无:没有激活的 Telegram Trigger)");
console.log("待推送更新:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
console.log("问题:Telegram 要求使用 HTTPS URL");
}
if (info.last_error_message) {
console.log("最近一次推送错误:", info.last_error_message);
}把 JavaScript 版本保存为 check.mjs,用 Node.js 18 或更高版本运行。结果这样解读:URL 指向别的服务,说明机器人的 Webhook 被其他程序接管了;pending_update_count 不断增长且出现 last_error_message,说明 Telegram 访问不到 n8n,或者 n8n 返回了错误。不想写代码的话,可以用 Bot API Tester 中的 getWebhookInfo。
第 4 步:从 n8n 发送 Telegram 消息
添加一个 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 写进工作流之前,可以先在 Bot API Tester 的 sendMessage 中发一条请求确认它可用。要在频道中发帖,需要先把机器人设为频道管理员。Telegram 大约允许每秒批量发送 30 条消息、单个聊天每秒约 1 条,群发循环要做限速;详见 Telegram Bot API 限制。
获取 chat id
最简单的来源就是触发器本身:运行工作流,给机器人发一条消息,然后在触发器输出中读取 message.chat.id。用户的 ID 是正数,普通群组是负数,超级群组和频道形如 -1001234567890。如果你更习惯用 getUpdates,请在该机器人的任何 Telegram Trigger 激活之前调用;设置了 Webhook 时它会返回 409 Conflict。包括群组、频道和论坛话题在内的所有方法,见 Telegram chat id 获取教程。
n8n Telegram 常见报错排查
| 现象 | 原因 | 解决方法 |
|---|---|---|
Bad Request: bad webhook: An HTTPS URL must be provided for webhook | n8n 注册的是 http:// URL:localhost,或者代理没有启用 TLS | 在代理上终止 TLS,并把 N8N_WEBHOOK_URL(或 WEBHOOK_URL)设为 HTTPS 地址 |
| 与端口有关的 bad webhook 错误 | 公网 URL 使用了 443、80、88、8443 以外的端口 | 通过代理在 443 端口暴露 n8n |
getUpdates 返回 409 Conflict | Telegram Trigger 保持着已注册的 Webhook | 停用工作流并调用 deleteWebhook,或者从触发器中获取 chat id |
| 工作流只在测试时正常,或只在发布后正常 | 测试和生产的 Webhook URL 互相覆盖 | 测试时取消发布,或使用单独的测试机器人 |
| 激活另一个工作流后,原来的触发器失效 | 第二个触发器或其他服务用同一个 Token 调用了 setWebhook | 每个机器人只用一个触发器;用 getWebhookInfo 检查 URL |
| 编辑器一直停在 “waiting for trigger event” | 反向代理不支持 WebSocket | 开启 WebSocket 代理,然后重新打开工作流 |
| 收不到群组消息 | 隐私模式:在群组中机器人只能收到发给它的命令、对它的回复和服务消息 | 用 /setprivacy 关闭隐私模式,或把机器人设为管理员 |
401 Unauthorized | 凭据中的 Token 错误或已被撤销 | 用 getMe 检查,并粘贴当前有效的 Token |
发送时返回 400 Bad Request: chat not found | chat id 错误,或机器人无法访问该聊天:用户从未启动过机器人,或机器人不在群组中 | 重新核对 ID;让用户先发送 /start,或把机器人加入群组 |
想从干净的状态重新开始:停用工作流,调用 deleteWebhook,确认 getWebhookInfo 显示的 url 为空,然后重新激活工作流,让 n8n 重新注册 URL。Webhook 的通用机制(secret token、重试、证书)见 Telegram Bot Webhook 设置教程。
常见问题
怎样把 Telegram 接入 n8n?
用 @BotFather 创建机器人,复制 Token,在 n8n 中新建 Telegram 凭据,把 Token 填入 Access Token。用 Telegram Trigger 节点接收消息,用 Telegram 节点发送消息,两个节点使用同一个凭据。
n8n 的 Telegram Trigger 为什么提示 “An HTTPS URL must be provided for webhook”?
触发器会调用 setWebhook 注册 Webhook,而 Telegram 只接受公网 HTTPS URL。如果 n8n 运行在 http://localhost 上,或者位于没有 TLS 的代理后面,请在 N8N_WEBHOOK_URL(旧版本为 WEBHOOK_URL)中填写实例的公网 HTTPS 地址,并在反向代理上终止 TLS。
两个 n8n 工作流能共用同一个 Telegram 机器人的触发器吗?
不可靠。一个机器人只有一个 Webhook URL,每次激活都会覆盖上一次的设置,只有最后一个工作流能收到更新。请做到一个机器人一个触发器,在同一个工作流内部分流,或者另建一个机器人。
配置 n8n 后,getUpdates 为什么返回 409 Conflict?
处于激活状态的 Telegram Trigger 会为机器人保持一个已注册的 Webhook,而设置了 Webhook 时 getUpdates 无法使用。需要轮询时先停用工作流并调用 deleteWebhook,或者直接从触发器的输出中读取 chat id。
只是从 n8n 发送 Telegram 消息,也需要公网 HTTPS 地址吗?
不需要。Telegram 节点只向 api.telegram.org 发起出站请求,所以本地运行的 n8n 也能发送消息。只有用 Telegram Trigger 接收更新时才需要公网 HTTPS。
n8n Telegram 节点需要的 chat id 去哪里找?
从触发器的输出中读取(message.chat.id),或者在触发器激活之前给机器人发消息,再调用 getUpdates。公开频道也可以直接使用 @channelusername。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。
Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。
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 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。
Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接
Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。
Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘
Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。
Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理
Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。
Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token
Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。
Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token
Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。
Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID
Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。
Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询
Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。
Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅
Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。
Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。
Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。
TelegramWidget JavaScript API:属性、事件、错误码与限制参考
TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。
Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端
Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。