Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器是一个独立的测试环境,有自己的账号和机器人,机器人在这里通过 https://api.telegram.org/bot<token>/test/METHOD_NAME 调用 Bot API。当你需要给 Mini App 或网页登录使用普通 HTTP 链接、需要一批可以随意丢弃的测试用户,或者要用目前只在测试环境开放的 Bot API 功能时,就该用它。日常测试 Telegram 机器人,往往在正式环境再建一个机器人就够了。本文介绍这两种方式,讲解如何在 iOS、Desktop 和 macOS 上登录测试环境,以及如何用 curl、Python、JavaScript 和我们的 Bot API Tester 调用测试接口。
方式一:在正式环境单独建一个测试机器人
想在不影响用户的前提下测试 Telegram 机器人,最快的办法是用另一个机器人账号运行一份代码副本:
- 在 @BotFather 中用
/newbot新建一个机器人(参见 Telegram 机器人创建教程)。 - 把它的 Token 写进测试实例的配置,例如单独的
.env文件。 - 用新机器人私下调试,正式机器人照常运行,互不干扰。
需要注意一点:file_id 与单个机器人 ID 绑定。测试机器人不能复用主机器人保存的 file_id,媒体文件需要由测试机器人重新上传。
方式二:使用独立的 Telegram 测试环境
对于更深入的测试,Telegram 还提供了专用的测试环境。它与正式(生产)环境完全隔离:正式环境的账号、机器人、聊天和 Token 在这里都不存在。主要区别如下:
| 正式环境 | 测试服务器 | |
|---|---|---|
| 用户账号 | 你平时用的 Telegram 账号 | 在测试环境中新注册的账号 |
| 机器人和 Token | 在正式环境通过 @BotFather 创建 | 在测试账号里通过 @BotFather 创建,Token 独立 |
| Bot API 地址 | /bot<token>/METHOD_NAME | /bot<token>/test/METHOD_NAME |
| Mini App 和网页登录链接 | 只能用 HTTPS | 允许不带 TLS 的 HTTP |
| 频率限制 | 标准限制 | 没有放宽,有时更严格 |
| 小组件(Bot API 10.4) | 仅限与机器人的私聊 | 还支持群组、inline 模式和转发 |
在 iOS、Desktop 或 macOS 上创建测试账号
用官方客户端登录 Telegram 测试环境:
- iOS:连续点击设置图标 10 次 → Accounts → Login to another account → Test。
- Telegram Desktop:打开 ☰ 设置,按住 Shift+Alt 并右键点击「添加账号」(Add Account),然后选择「Test Server」。
- macOS:连续点击设置图标 10 次打开 Debug Menu,然后 ⌘+点击「添加账号」(Add Account),用手机号登录。
测试账号会和你的常用账号并列显示,在同一个客户端里就能切换环境。你在测试账号中的一切操作,包括和测试机器人的聊天,都只存在于测试环境。
在测试服务器上创建机器人并获取 Token
在测试账号里打开 @BotFather,按常规流程创建机器人:/newbot,输入显示名称,再输入以 bot 结尾的用户名。BotFather 会返回一个测试环境专用的 Token。它看起来和普通 Token 一样,但只能配合 /test/ 接口地址使用。建议用单独的变量名保存,比如 TEST_BOT_TOKEN,避免和正式 Token 混淆;Telegram Bot Token 教程中的安全建议在这里同样适用。
在 Telegram 测试服务器上调用 Bot API
所有 Bot API 方法的用法都不变,唯一的区别是 Token 后面多了 /test/。先用 getMe 检查 Token:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"
在代码中把基础地址放在一个常量里,切换环境只需改一行。下面这个最小回声机器人先检查 Token,然后通过 getUpdates 长轮询接收更新,遇到 429 时按 retry_after 的要求等待:
import os
import time
import requests
TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test" # 正式环境去掉 "/test"
def call(method, **params):
while True:
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if data["ok"]:
return data["result"]
if data.get("error_code") == 429: # 触发频率限制:按要求等待
time.sleep(data["parameters"]["retry_after"])
continue
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
me = call("getMe")
print("已在测试服务器上运行:@" + me["username"])
offset = 0
while True:
for update in call("getUpdates", offset=offset, timeout=30):
offset = update["update_id"] + 1
msg = update.get("message")
if msg and "text" in msg:
call("sendMessage", chat_id=msg["chat"]["id"], text="测试回声:" + msg["text"])const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // 正式环境去掉 "/test"
async function call(method, params = {}) {
while (true) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (data.ok) return data.result;
if (data.error_code === 429) { // 触发频率限制:按要求等待
await new Promise((resolve) => setTimeout(resolve, data.parameters.retry_after * 1000));
continue;
}
throw new Error(`${method}: ${data.error_code} ${data.description}`);
}
}
const me = await call("getMe");
console.log("已在测试服务器上运行:@" + me.username);
let offset = 0;
while (true) {
for (const update of await call("getUpdates", { offset, timeout: 30 })) {
offset = update.update_id + 1;
const msg = update.message;
if (msg?.text) {
await call("sendMessage", { chat_id: msg.chat.id, text: "测试回声:" + msg.text });
}
}
}用测试账号给机器人发送 /start,它就会回复。JavaScript 版本使用了顶层 await,请保存为 bot.mjs,并用 Node.js 18 或更高版本运行。
Webhook 的用法也一样:通过测试地址调用 setWebhook,url、端口和 secret_token 的规则不变。之后同样通过 /test/ 调用 getWebhookInfo 检查结果:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/setWebhook" \
-d "url=https://example.com/telegram/webhook"
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getWebhookInfo"
机器人开发库通常根据一个基础地址拼接请求 URL。如果你用的库支持自定义 Bot API 基础地址,把它设置成最终请求落在 …/bot<token>/test/METHOD_NAME 即可;各个库的配置项名称不同,请查阅对应库的文档。
在 Bot API Tester 中试用测试服务器
我们的 Bot API Tester 不写代码也能向测试环境发送请求:
- 打开 Bot API Tester 中的 getMe。
- 点击 Token 输入框旁边的 TEST 开关,或在页面地址后加上
?env=test打开。 - 粘贴测试机器人的 Token,点击执行。此时请求会发送到
https://api.telegram.org/bot<token>/test/METHOD。
开关打开期间,所有方法都使用测试地址,包括 getUpdates 长轮询,因此你可以在更新历史中看到来自测试账号的消息。Tester 会在浏览器中记住开关状态,粘贴正式 Token 之前记得关掉它。和往常一样,Token 只保存在浏览器的 localStorage 中,请求直接发往 api.telegram.org。
通过普通 HTTP 调试 Mini App 和网页登录
Mini App 开发者使用测试环境的主要原因是:在这里,WebAppInfo(Mini App)和 LoginUrl(网页登录按钮)中的 url 可以是不带 TLS 的 HTTP 链接。这样就能把测试机器人的菜单按钮或 web_app 按钮直接指向局域网里的开发服务器,不必配置证书或内网穿透。正式环境的链接必须使用 HTTPS。在接入 Telegram 之前,也可以先用 Mini App Tester 的模拟模式在普通浏览器里调试 Telegram.WebApp 接口。
测试服务器上的 Bot API 10.4 小组件
Bot API 10.4 新增的消息内 HTML 小组件,目前在正式环境中只能用于与机器人的私聊。群组、inline 模式和转发消息中的小组件暂时只在测试服务器上可用,想测试这些场景就要用测试环境。小组件的工作原理见 Telegram 小组件入门。
频率限制与最佳实践
- 不要在测试环境做压力测试。测试环境没有放宽频率限制,有时甚至更严格。请按
retry_after处理429,不要依赖写死的限制数值;各方法的参数可在 Bot API 方法参考中查阅。 - 在配置中区分环境。Token 和基础地址分别用独立的变量,并在启动日志里打印当前所在的环境。
- 上线前回到正式环境再测一遍。发布之前,用正式环境的测试机器人通过 HTTPS 把相同场景再跑一遍,因为 HTTP 链接和测试环境独有的功能对真实用户无效。
常见问题排查
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
401 Unauthorized | 把正式 Token 发到了 /test/,或测试 Token 没有带 /test/ | 两个环境相互独立:让 Token 与地址(或 Tester 中的 TEST 开关)保持一致 |
400 Bad Request: chat not found | chat id 来自正式环境,这些用户和聊天在测试服务器上不存在 | 用测试账号给测试机器人发消息,再从 getUpdates 中获取 chat id |
| 搜索不到机器人 | 在正式账号里搜索 | 切换到创建该机器人的测试账号再搜索 |
429 Too Many Requests | 触发频率限制,测试服务器并未放宽 | 等待 retry_after 秒并降低发送频率 |
| HTTP 地址的 Mini App 打不开 | 机器人或账号属于正式环境 | 使用在测试环境中创建的机器人,并从测试账号打开 |
常见问题
Telegram 测试服务器是什么?
它是一个与正式环境完全隔离的测试环境,有独立的用户账号和机器人。机器人通过 https://api.telegram.org/bot<token>/test/METHOD_NAME 调用 Bot API。
怎样登录 Telegram 测试环境?
iOS:连续点击设置图标 10 次 → Accounts → Login to another account → Test。Telegram Desktop:打开 ☰ 设置,按住 Shift + Alt 并右键点击「添加账号」→ Test Server。macOS:连续点击设置图标 10 次打开 Debug Menu,然后 ⌘ + 点击「添加账号」。
正式环境的机器人 Token 能在测试服务器上用吗?
不能。两个环境相互独立,在正式环境创建的机器人在测试服务器上并不存在,反之亦然。请在测试账号里通过 @BotFather 新建机器人;Token 与环境不匹配时通常会返回 401 Unauthorized。
Telegram 测试服务器的频率限制更宽松吗?
不会。测试环境没有放宽频率限制,有时甚至更严格。请按 retry_after 处理 429 Too Many Requests,不要在代码里写死限制数值。
测试环境中的 Mini App 可以用 HTTP 吗?
可以。在测试环境中,WebAppInfo(Mini App)和 LoginUrl(网页登录)的 url 可以是不带 TLS 的 HTTP 链接;正式环境必须使用 HTTPS。
测试机器人一定要用测试服务器吗?
不一定。大多数情况下,在正式环境用 @BotFather 再建一个机器人就够了:它有自己的 Token,不会打扰真实用户。只有需要 HTTP 链接、独立的测试账号或仅在测试服务器上开放的功能时,才需要用测试服务器。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
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 网站小部件教程:用 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 的区别。