Telegram 机器人 webhook 设置：开发者完整指南

Telegram 机器人 webhook 设置将您的服务器连接到 Telegram 的更新流，以便消息实时到达，而不是通过轮询循环。如果您正在使用 Bot API 构建自定义机器人，webhooks 是标准的生产路径：Telegram 将每个更新 POST 到您的 HTTPS 端点，您的代码会响应。

本指南将介绍先决条件、注册、一个可用的处理程序示例、验证、故障排除，以及何时使用像 TeleClaw 这样的托管平台比自托管更有意义。

主要收获

• Webhooks 和长轮询是互斥的。 设置 webhook 会禁用 getUpdates，直到您将其删除。
• HTTPS 是强制性的。 您的端点需要 TLS 1.2+、匹配的证书和端口 443、80、88 或 8443。
• 使用 setWebhook 注册，使用 getWebhookInfo 验证。 当更新停止流动时，检查 last_error_message。
• 使用 secret_token 确认请求来自 Telegram，而不是随机扫描器访问您的 URL。
• 无代码替代方案： TeleClaw 处理托管和交付，因此您可以完全跳过服务器层。

Webhooks 与长轮询：如何选择

Telegram 提供两种接收更新的方式。根据 Bots FAQ，您为每个机器人选择一种方法。您不能同时运行两种方法。

长轮询是原型开发最快的方式。您的机器人循环调用 getUpdates，处理每个批次，并推进偏移量。没有域名，没有证书，没有开放端口。

Webhooks 颠覆了这种模式。每当有人向机器人发送消息时，Telegram 就会向您的 URL 发送一个 HTTPS POST。这消除了空闲轮询请求并缩短了响应时间，这对于支持机器人、支付流程和大规模群组管理至关重要。

如果您仍在注册机器人本身，请从我们的 创建 Telegram 机器人指南 开始，从 BotFather 获取令牌，然后再继续。

Telegram 机器人 webhook 设置的先决条件

在调用 setWebhook 之前，请确认您的基础设施符合 Telegram 官方 webhook 指南 中的要求：

• 来自 @BotFather 的 机器人令牌（请参阅上面链接的创建机器人指南）。
• 具有有效 TLS 证书的 公共域名。自签名证书仅在您通过 certificate 参数上传公钥时才有效。
• 您的服务器上 支持的端口：443（默认）、80、88 或 8443。其他端口将被拒绝。
• 证书 CN 或 SAN 必须与您的 webhook URL 中的域名匹配。通配符证书可能不起作用。不支持重定向。
• 来自 Telegram 子网 149.154.160.0/20 和 91.108.4.0/22 的 入站 POST 访问。

对于本地开发，通过隧道（ngrok、Cloudflare Tunnel 或类似工具）暴露 localhost，为您提供公共 HTTPS URL。在注册 webhook 之前，测试隧道是否为 POST 请求返回 HTTP 200。

步骤 1：构建您的 webhook 端点

您的服务器需要一个接受 POST 请求、解析 JSON Update 对象并快速返回 HTTP 200 的路由。缓慢的处理程序会导致 Telegram 重试并最终在 getWebhookInfo 中报告错误。

使用 Express 的最小 Node.js 示例：

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

使用 Flask 的 Python 遵循相同的模式：从 request 读取 JSON，如果配置了则验证秘密头，处理更新，返回 200。

快速响应。 繁重的工作（数据库写入、AI API 调用）应该进入后台队列。Telegram 期望快速确认。您还可以通过返回带有 method 字段的 JSON 正文而不是进行单独的 API 调用来内联回复，如 Bot API webhook 注释 中所述。

步骤 2：使用 setWebhook 配置 Telegram 机器人 webhook

一旦您的端点上线，请将其注册到 Bot API。将 <TOKEN> 和 URL 替换为您的值。

使用 curl：

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

参数参考：

• url（必需）：您的 HTTPS 端点。使用空字符串删除 webhook。
• secret_token（可选）：1-256 个字符（A-Z、a-z、0-9、_、-）。Telegram 在 X-Telegram-Bot-Api-Secret-Token 头中发送它。
• max_connections（可选）：1-100 个并发连接。默认值为 40。
• allowed_updates（可选）：限制您接收的更新类型。如果您只处理消息，则会减少有效负载大小。
• drop_pending_updates（可选）：当切换 webhook 时，设置为 true 以丢弃排队的更新。
• certificate（可选）：为自签名证书上传您的公钥文件。

成功的响应如下所示：{"ok":true,"result":true,"description":"Webhook was set"}。

步骤 3：使用 getWebhookInfo 验证

始终立即确认注册。当更新停止到达时，这是您的第一个故障排除工具。

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

示例响应：

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

关注这些字段：

• url：为空表示没有活动的 webhook（机器人处于长轮询状态）。
• pending_update_count：等待交付的排队更新。数量增加表示交付失败。
• last_error_date 和 last_error_message：最近的失败原因。修复根本原因后，Telegram 会自动重试。
• ip_address：当前访问您的端点的 Telegram IP。

从真实的 Telegram 帐户向您的机器人发送测试消息。如果 pending_update_count 保持为零并且您的服务器日志显示 POST，则 Telegram 机器人 webhook 设置正在工作。

Telegram 机器人 webhook 示例：加入请求处理程序

加入请求机器人（Guardian 风格的入场流程）需要 chat_join_request 更新类型。我们的 Guardian 机器人指南 涵盖了产品方面。这是 webhook 连接。

注册并启用加入请求：

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

处理程序逻辑（伪代码）：

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Run screening logic, then approve or decline via Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram 将加入请求作为推送更新交付，因此 webhooks 非常适合需要在请求过期前响应的入场机器人。

Telegram 机器人删除 webhook 并切换回轮询

需要使用 getUpdates 在本地调试？首先删除 webhook。

选项 A 使用 deleteWebhook：

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

选项 B 使用 setWebhook 和空 URL：

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

这两种方法都会重新启用长轮询。如果您跳过此步骤，getUpdates 将不返回任何内容，因为 webhook 仍注册到您的生产 URL。

常见 webhook 错误故障排除

当 getWebhookInfo 显示错误时，将消息与修复方法匹配：

在生产环境中按计划运行 getWebhookInfo。及早捕获 last_error_message 可以防止数小时的静默消息丢失。

跳过服务器：使用 TeleClaw 管理机器人

并非每个机器人都需要自定义 webhook 基础设施。如果您的目标是为群组或商业频道提供 AI 助手，那么托管和更新交付是已解决的问题。

TeleClaw 将您的 BotFather 令牌连接到由 OpenClaw 提供支持的托管运行时。您可以在仪表板中配置个性、知识库和审核规则。该平台处理 HTTPS 端点、扩展和 AI 模型路由。将 @claw 添加为群组管理员，无需编写 webhook 处理程序即可上线。

在 TeleClaw 功能页面 上探索托管机器人可以做什么。有关完整的无代码演练，请参阅我们的 Telegram 无代码聊天机器人指南。

当您需要完全控制时，自定义 webhooks 仍然有意义：专有后端、受监管的数据驻留或非标准更新处理。对于其他所有情况，证书管理、监控和重试处理的运营成本会迅速增加。

结论

Telegram 机器人 webhook 设置归结为四个步骤：部署 HTTPS 端点，调用 setWebhook，使用 getWebhookInfo 验证，并监控错误。使用 secret_token 进行请求验证，将 allowed_updates 限制为您处理的内容，并保持处理程序快速。

希望在不运行服务器的情况下实现生产推送交付的开发人员可以使用 TeleClaw。粘贴您的令牌，配置 AI 行为，并专注于机器人说什么，而不是更新如何到达。

准备好在不管理 webhooks 的情况下启动 AI 机器人了吗？ 将 @claw 添加到您的 Telegram 群组 →