Telegram 机器人 Webhook 检查工具
一键检查 Telegram 机器人的 Webhook:工具会调用 getWebhookInfo,显示 URL、待处理更新数和最近一次投递错误及修复建议,还可以设置或删除 Webhook。
Token 只保存在你的浏览器中(localStorage),并且只发送到 api.telegram.org。
设置或修改 Webhook
如何检查 Telegram 机器人的 Webhook
- 粘贴 Bot Token。如果机器人位于测试环境,请勾选测试服务器。
- 点击检查 Webhook。你会得到三种结果之一:没有 Webhook(机器人使用
getUpdates)、Webhook 在过去 24 小时内没有错误,或者存在投递问题,并显示最近一次错误的时间、内容和修复建议。 - 查看待处理更新计数。超过 100 时会高亮显示:说明更新在堆积,因为你的服务器没有接收它们。
- 下方会显示完整的
getWebhookInfo响应:url、has_custom_certificate、pending_update_count、last_error_date、last_error_message、max_connections等字段。 - 要修改设置,请展开设置或修改 Webhook:输入 HTTPS URL 和可选的
secret_token,选择是否丢弃待处理更新,然后点击 setWebhook 或 deleteWebhook。之后会自动重新检查。
常见的 Webhook 错误
修复建议是根据 last_error_message 的内容选出的:
| 错误类似于 | 需要检查什么 |
|---|---|
| SSL / certificate | 域名的有效证书(或通过 setWebhook 的 certificate 参数上传的自签名证书),TLS 1.2+。 |
| Wrong response from the webhook: 4xx/5xx | 路径、你的 secret_token 校验和服务器错误——Telegram 期望 2xx。 |
| Timeout / connection reset | 服务器必须能从互联网通过 443、80、88 或 8443 端口访问,并且快速响应。 |
| Connection refused | 该端口上没有服务在监听,或者防火墙拦截了 Telegram。 |
| Host can't be resolved | Webhook 域名的 DNS 记录。 |
表单只发送 url、secret_token 和 drop_pending_updates。secret(1–256 个字符,A-Z a-z 0-9 _ -)会出现在每个请求的 X-Telegram-Bot-Api-Secret-Token 请求头中。如需设置 allowed_updates、max_connections 或证书,请使用 /zh/telegram-bot-api-tester.html#setWebhook。
隐私
Token 保存在你浏览器的 localStorage 中,getWebhookInfo、setWebhook 和 deleteWebhook 都直接发送到 api.telegram.org,不经过我们的服务器。同样的调用也可以在 /zh/telegram-bot-api-tester.html#getWebhookInfo 中完成。完整的设置步骤见 /zh/guides/telegram-bot-webhook.html,409 Conflict 等错误的说明见 /zh/guides/telegram-bot-api-errors.html。
常见问题
如何检查 Telegram 机器人是否设置了 Webhook?
调用 getWebhookInfo。如果 url 为空,说明没有设置 Webhook,机器人通过 getUpdates 工作。上方的检查工具会替你调用并解释结果。
如何删除 Telegram 机器人的 Webhook?
调用 deleteWebhook——在工具中展开设置或修改 Webhook,点击 deleteWebhook。只有想丢弃队列中的更新时才勾选丢弃待处理更新。之后 getUpdates 就能重新使用了。
为什么 pending_update_count 一直在增长?
Telegram 无法投递更新:你的服务器无法访问、响应太慢,或者返回了非 2xx 状态码。查看 last_error_message;Telegram 会持续重试,更新最多保存 24 小时。
“Wrong response from the webhook”是什么意思?
你的服务器返回了 2xx 以外的 HTTP 状态码,例如路径错误时的 404 或程序崩溃时的 500。Telegram 期望快速收到 2xx 响应,否则会重试。
其他工具
Chat ID 查询工具MarkdownV2 与 HTML 转义工具Mini App initData 校验工具Bot API Tester