Telegram Bot API

n8n Telegram 集成教程:连接机器人、触发工作流并发送消息

· 8 分钟阅读

把 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

  1. 打开 @BotFather,发送 /newbot,设置显示名称和以 bot 结尾的用户名。
  2. 复制 BotFather 返回的 Token,格式类似 123456789:AAEexampleTokenReplaceWithYours。已有的机器人可以通过 /mybots → 选择机器人 → API Token 查看。
  3. 在粘贴到任何地方之前,先检查 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。由此带来两点影响:

让自托管 n8n 可以通过 HTTPS 访问

n8n Cloud 自带公网 HTTPS 地址。自托管实例则根据自身的协议、主机名和端口生成 Webhook URL,在反向代理后面或 localhost 上,这通常是一个会被 Telegram 拒绝的 http:// 地址。解决方法:

  1. 把 n8n 放在反向代理(nginx、Caddy、Traefik 等)后面,由代理在 443 端口用有效证书终止 TLS。
  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 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,选好凭据后填写两个字段:

有两个默认设置常常让人意外。第一,节点会在消息末尾附加一行 This message was sent automatically with n8n,在附加字段中关闭 Append n8n Attribution 即可去掉。第二,节点的解析模式默认是 HTML,所以动态文本中的 <、> 和 & 要转义为 &lt;、&gt; 和 &amp;,否则 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 webhookn8n 注册的是 http:// URL:localhost,或者代理没有启用 TLS在代理上终止 TLS,并把 N8N_WEBHOOK_URL(或 WEBHOOK_URL)设为 HTTPS 地址
与端口有关的 bad webhook 错误公网 URL 使用了 443、80、88、8443 以外的端口通过代理在 443 端口暴露 n8n
getUpdates 返回 409 ConflictTelegram 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 foundchat 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 校验代码。