Telegram Bot API

Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人

· 7 分钟阅读

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 机器人,最快的办法是用另一个机器人账号运行一份代码副本:

  1. 在 @BotFather 中用 /newbot 新建一个机器人(参见 Telegram 机器人创建教程)。
  2. 把它的 Token 写进测试实例的配置,例如单独的 .env 文件。
  3. 用新机器人私下调试,正式机器人照常运行,互不干扰。

需要注意一点: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 测试环境:

测试账号会和你的常用账号并列显示,在同一个客户端里就能切换环境。你在测试账号中的一切操作,包括和测试机器人的聊天,都只存在于测试环境。

在测试服务器上创建机器人并获取 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 不写代码也能向测试环境发送请求:

  1. 打开 Bot API Tester 中的 getMe。
  2. 点击 Token 输入框旁边的 TEST 开关,或在页面地址后加上 ?env=test 打开。
  3. 粘贴测试机器人的 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 小组件入门。

频率限制与最佳实践

常见问题排查

现象可能原因解决方法
401 Unauthorized把正式 Token 发到了 /test/,或测试 Token 没有带 /test/两个环境相互独立:让 Token 与地址(或 Tester 中的 TEST 开关)保持一致
400 Bad Request: chat not foundchat 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 的区别。