Telegram Test Server: How to Test a Bot in the Telegram Test Environment
The Telegram test server is a separate test environment with its own accounts and bots, where your bot calls the Bot API at https://api.telegram.org/bot<token>/test/METHOD_NAME. Use it when you need plain HTTP links for Mini Apps or Web Login, a set of throwaway test users, or Bot API features that are currently enabled only there. For everyday testing, a second bot in production is often enough. This guide covers both options, how to log in to the test environment on iOS, Desktop and macOS, and how to call the test API from curl, Python, JavaScript and our Bot API Tester.
Option 1: a separate test bot in production
The quickest way to test a Telegram bot without interfering with its users is to run a second instance of your code on a different bot account:
- Create a new bot with
/newbotin @BotFather (see how to create a Telegram bot). - Put its token into the configuration of your test instance, for example a separate
.envfile. - Debug privately with the new bot; the production bot keeps running untouched.
One catch: a file_id is tied to a single bot id. A test bot cannot reuse file_id values stored by the main bot, so media must be uploaded again by the test bot.
Option 2: the dedicated Telegram test environment
Telegram also runs a dedicated test environment for more advanced testing. It is completely separate from the main (production) environment: production accounts, bots, chats and tokens don't exist there. Here is what changes:
| Production | Test server | |
|---|---|---|
| User account | Your normal Telegram account | A new account created in the test environment |
| Bots and tokens | Created with @BotFather in production | Created with @BotFather inside the test account; separate tokens |
| Bot API URL | /bot<token>/METHOD_NAME | /bot<token>/test/METHOD_NAME |
| Mini App and Web Login links | HTTPS only | HTTP without TLS allowed |
| Flood limits | Standard limits | Not raised, may at times be stricter |
| Widgets (Bot API 10.4) | Private chat with the bot only | Also groups, inline mode and forwards |
Create a test account on iOS, Desktop or macOS
Log in to the Telegram test environment from an official app:
- iOS: tap the Settings icon 10 times → Accounts → Login to another account → Test.
- Telegram Desktop: open ☰ Settings, hold Shift+Alt and right-click "Add Account", then select "Test Server".
- macOS: click the Settings icon 10 times to open the Debug Menu, then ⌘+click "Add Account" and log in via phone number.
The test account is added next to your regular one, so you can switch between environments in the same app. Everything you do there, including chats with your test bot, stays in the test environment.
Create a bot on the test server and get its token
Inside the test account, open @BotFather and create a bot the usual way: /newbot, a display name, then a username ending in bot. BotFather replies with a token for the test environment. It looks like any other token, but it only works with the /test/ API URL. Store it under a separate name, for example TEST_BOT_TOKEN, so it never gets mixed up with the production one; the rules from the bot token guide apply here too.
Call the Bot API on the Telegram test server
All Bot API methods work the same way; the only difference is /test/ after the token. Check the token with getMe:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"
In code, keep the base URL in one constant so switching between environments is a one-line change. This minimal echo bot checks the token, then receives updates with getUpdates long polling and waits on 429 as instructed by retry_after:
import os
import time
import requests
TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test" # remove "/test" for production
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: # flood limit: wait as told
time.sleep(data["parameters"]["retry_after"])
continue
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
me = call("getMe")
print("Running on the test server as @" + 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="Test echo: " + msg["text"])const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // remove "/test" for production
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) { // flood limit: wait as told
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("Running on the test server as @" + 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: "Test echo: " + msg.text });
}
}
}Send /start to the bot from your test account and it answers. The JavaScript version uses top-level await, so save it as bot.mjs and run it with Node.js 18 or newer.
Webhooks work the same way: call setWebhook through the test URL, and the usual rules for url, ports and secret_token apply. Check the result with getWebhookInfo, also through /test/:
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"
Bot libraries usually build request URLs from a base address. If yours lets you override the Bot API base URL, set it so that requests end up at …/bot<token>/test/METHOD_NAME; the exact option name differs between libraries, so look it up in your library's documentation.
Try the test server in the Bot API Tester
Our Bot API Tester can send requests to the test environment without any code:
- Open getMe in the Bot API Tester.
- Press the TEST switch next to the token field, or open the tester page with
?env=testin the address. - Paste the token of your test bot and press Execute. Requests now go to
https://api.telegram.org/bot<token>/test/METHOD.
Every method uses the test URL while the switch is on, including getUpdates long polling, so you can watch updates from your test account arrive in the update history. The tester remembers the switch in your browser; turn it off before you paste a production token. As always, the token stays in your browser's localStorage and requests go straight to api.telegram.org.
Mini Apps and Web Login over plain HTTP
The main reason Mini App developers use the test environment: there, the url in WebAppInfo (Mini Apps) and LoginUrl (Web Login buttons) may be an HTTP link without TLS. That lets you point a test bot's menu button or web_app button at a dev server on your local network without setting up certificates or a tunnel. Production links must use HTTPS. The full Mini App workflow, from browser mock mode to initData validation, is in how to test a Telegram Mini App.
Bot API 10.4 widgets on the test server
HTML widgets in messages, added in Bot API 10.4, currently work in production only in the private chat with the bot. Widgets in groups, in inline mode and in forwarded messages work only on the test server for now, so that is where you can try those scenarios. See Telegram widgets for how widgets work.
Limits and good practice
- Don't load-test there. Flood limits are not raised in the test environment and may at times be stricter. Handle
429withretry_afterand don't depend on hardcoded limit values; Telegram Bot API limits explains the numbers and retry logic. - Keep environments apart in config. Use separate variables for the token and the base URL, and log which environment the bot started in.
- Re-test in production. Before release, run the same scenarios with a production test bot over HTTPS, because HTTP links and test-only features won't work for real users.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized | A production token sent to /test/, or a test token sent without /test/ | The environments are separate: match the token to the URL (or the TEST switch in the tester) |
400 Bad Request: chat not found | The chat id comes from production; those users and chats don't exist on the test server | Message the test bot from your test account and take the chat id from getUpdates |
| Can't find the bot in search | Searching from your production account | Search from the test account, where the bot was created |
429 Too Many Requests | Flood limits, which are not raised on the test server | Wait retry_after seconds and slow down |
| Mini App over HTTP doesn't open | The bot or account is in production | Use a bot created in the test environment and open it from the test account |
Frequently asked questions
What is the Telegram test server?
A dedicated test environment that is completely separate from production Telegram. It has its own user accounts and its own bots, and bots call the Bot API at https://api.telegram.org/bot<token>/test/METHOD_NAME.
How do I log in to the Telegram test environment?
On iOS tap the Settings icon 10 times → Accounts → Login to another account → Test. In Telegram Desktop open ☰ Settings, press Shift + Alt and right-click Add Account → Test Server. On macOS click the Settings icon 10 times to open the Debug Menu, then ⌘ + click Add Account.
Can I use my production bot token on the test server?
No. The environments are separate, so a bot created in production does not exist on the test server and vice versa. Create a new bot with @BotFather inside your test account; using the wrong token for the environment typically ends in 401 Unauthorized.
Are rate limits higher on the Telegram test server?
No. Flood limits are not raised in the test environment and may at times be stricter, so handle 429 Too Many Requests with retry_after and don't hardcode limit values.
Can a Mini App use plain HTTP in the test environment?
Yes. In the test environment the url of WebAppInfo (Mini Apps) and LoginUrl (Web Login) may be an HTTP link without TLS. Production links must use HTTPS.
Do I always need the test server to test a bot?
No. For most work, a second bot created with @BotFather in production is enough: it has its own token and doesn't interfere with your real users. Use the test server when you need HTTP links, separate test accounts or features available only there.
Related guides
How to Create a Telegram Bot: Step by Step with BotFather and Python
How to create a Telegram bot step by step: register it with @BotFather, get the token, test it with getMe and send a first message with curl or Python.
Telegram Bot API 10.0–10.5: Bot Settings, Widgets, Rich Messages, Ephemeral Messages, Guest Mode and More
What's new in Telegram Bot API 10.0–10.5: setMySettings and BotFullInfo, HTML widgets, rich and ephemeral messages, guest mode, with JSON examples.
Telegram Bot API Limits: Rate Limits, 429 Errors, File Sizes and Message Length
Telegram Bot API rate limits explained: 30 msg/s, 1 msg/s per chat, 20/min in groups, handling 429 retry_after, plus file size and message length limits.
How to Send a Message with the Telegram Bot API (sendMessage)
Telegram Bot API send message guide: sendMessage with curl, Python and JavaScript, HTML and MarkdownV2 formatting, inline buttons and error fixes.
Telegram Bot Token: How to Get It, Find It Again, Check It and Keep It Safe
Telegram bot token guide: get one from @BotFather, find the token of an existing bot, check it with getMe, revoke a leaked token and store it safely.
How to Set Up a Telegram Bot Webhook: setWebhook, Secret Token and Troubleshooting
Set up a Telegram bot webhook: setWebhook URL requirements, secret_token header check, getWebhookInfo debugging, deleteWebhook and fixes for n8n.
How to Get a Telegram Chat ID for a User, Group, Channel or Topic
How to get a Telegram chat ID for a user, group, supergroup, channel or forum topic with getUpdates, plus fixes for an empty result and 409 Conflict.
Telegram Widgets for Your Website: Login Widget, Post Embed, Discussion and Share Button
Add Telegram to your website: the new Telegram Login (OIDC), the legacy Login Widget with hash check code, post embeds, comments and a share button.
TelegramWidget JavaScript API: Reference, Events, Error Codes and Limits
TelegramWidget JavaScript API reference: properties, request(), events, error codes, CSS variables, widget_query and answerWidgetQuery, plus every limit.
Telegram Widget Examples: Complete HTML and Python Bot Code
Working Telegram widget examples with full code: a static order card, a counter with widget_query requests, a shared live poll and a local preview stub.
Telegram Widgets: Interactive HTML Inside Bot Messages
Telegram widgets (Bot API 10.4): what they are, how sendWidget, chat_data and public_data work, where they run today and how they differ from Mini Apps.
How to Test a Telegram Mini App: From Browser Mock to Real Telegram
Test a Telegram Mini App step by step: browser mock mode, localhost via HTTPS tunnel, test environment, DevTools per platform, initData validation.