Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram — это отдельное тестовое окружение со своими аккаунтами и ботами, где бот обращается к Bot API по адресу https://api.telegram.org/bot<token>/test/METHOD_NAME. Он нужен, когда Mini App или Web Login должны открываться по обычному HTTP, когда нужны одноразовые тестовые пользователи или функции Bot API, которые пока включены только там. Для повседневного тестирования часто достаточно второго бота в обычном Telegram. Ниже — оба варианта, вход в тестовое окружение на iOS, Desktop и macOS и запросы к тестовому API из curl, Python, JavaScript и нашего Bot API Tester.
Вариант 1: отдельный тестовый бот в рабочем Telegram
Самый быстрый способ протестировать Telegram-бота, не мешая его пользователям, — запустить вторую копию кода на другом боте:
- Создайте нового бота командой
/newbotв @BotFather (подробно — в гайде как создать бота в Telegram). - Пропишите его токен в конфигурацию тестового экземпляра, например в отдельный файл
.env. - Отлаживайте всё на новом боте — рабочий бот продолжает работать как раньше.
Есть нюанс: file_id привязан к конкретному боту. Тестовый бот не сможет использовать file_id, сохранённые основным ботом, поэтому файлы придётся загрузить заново уже от его имени.
Вариант 2: отдельное тестовое окружение Telegram
Для более серьёзного тестирования у Telegram есть выделенное тестовое окружение. Оно полностью отделено от основного (рабочего): обычных аккаунтов, ботов, чатов и токенов там нет. Что меняется:
| Рабочее окружение | Тестовый сервер | |
|---|---|---|
| Аккаунт | Ваш обычный аккаунт Telegram | Новый аккаунт, созданный в тестовом окружении |
| Боты и токены | Создаются в @BotFather в обычном Telegram | Создаются в @BotFather из тестового аккаунта; токены свои |
| Адрес Bot API | /bot<token>/METHOD_NAME | /bot<token>/test/METHOD_NAME |
| Ссылки Mini App и Web Login | Только HTTPS | Разрешён HTTP без TLS |
| Flood-лимиты | Стандартные | Не повышены, иногда строже |
| Виджеты (Bot API 10.4) | Только личный чат с ботом | Ещё группы, inline-режим и пересылки |
Как создать тестовый аккаунт на iOS, Desktop и macOS
Войти в тестовое окружение Telegram можно из официальных приложений:
- iOS: 10 раз нажмите на иконку настроек → Accounts → Login to another account → Test.
- Telegram Desktop: откройте ☰ Settings, зажмите Shift+Alt и кликните правой кнопкой по «Add Account», затем выберите «Test Server».
- macOS: 10 кликов по иконке настроек откроют Debug Menu, затем ⌘+клик по «Add Account» и вход по номеру телефона.
Тестовый аккаунт добавляется рядом с обычным, так что переключаться между окружениями можно в одном приложении. Всё, что вы делаете в тестовом аккаунте, включая переписку с тестовым ботом, остаётся в тестовом окружении.
Создайте бота на тестовом сервере и получите токен
В тестовом аккаунте откройте @BotFather и создайте бота как обычно: /newbot, отображаемое имя, затем username, который заканчивается на bot. BotFather пришлёт токен для тестового окружения. Выглядит он как любой другой токен, но работает только с адресом /test/. Храните его под отдельным именем, например TEST_BOT_TOKEN, чтобы не перепутать с рабочим; все правила из гайда о токене бота действуют и здесь.
Запросы к Bot API на тестовом сервере Telegram
Все методы Bot API работают так же, разница только в /test/ после токена. Проверьте токен методом getMe:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"
В коде держите базовый адрес в одной константе — тогда переход между окружениями сводится к одной строке. Этот минимальный эхо-бот проверяет токен, получает апдейты через long polling 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: # flood-лимит: ждём, сколько сказано
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) { // flood-лимит: ждём, сколько сказано
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 или новее.
С вебхуками всё так же: вызывайте setWebhook через тестовый адрес, а требования к url, портам и secret_token остаются прежними. Результат проверяйте через getWebhookInfo, тоже с /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"
Библиотеки для ботов обычно собирают адрес запроса из базового URL. Если ваша библиотека позволяет переопределить базовый адрес Bot API, настройте его так, чтобы запросы уходили на …/bot<token>/test/METHOD_NAME. Название опции в разных библиотеках разное — уточните его в документации.
Тестовый сервер в Bot API Tester
Наш Bot API Tester умеет отправлять запросы в тестовое окружение без единой строки кода:
- Откройте getMe в Bot API Tester.
- Нажмите переключатель TEST рядом с полем токена или откройте страницу тестера с
?env=testв адресе. - Вставьте токен тестового бота и нажмите Execute. Теперь запросы идут на
https://api.telegram.org/bot<token>/test/METHOD.
Пока переключатель включён, тестовый адрес используют все методы, в том числе long polling getUpdates, так что апдейты из тестового аккаунта появляются в истории. Тестер запоминает положение переключателя в браузере — выключите его, прежде чем вставлять рабочий токен. Токен, как и всегда, хранится только в localStorage вашего браузера, а запросы идут напрямую на api.telegram.org.
Mini Apps и Web Login по обычному HTTP
Главная причина, по которой разработчики Mini Apps заходят в тестовое окружение: там в поле url объектов WebAppInfo (Mini Apps) и LoginUrl (кнопки Web Login) можно указать HTTP-ссылку без TLS. Значит, кнопку меню или web_app-кнопку тестового бота можно направить прямо на dev-сервер в локальной сети — без сертификатов и туннелей. В рабочем окружении ссылки должны быть HTTPS. Весь процесс тестирования Mini App, от mock-режима в браузере до проверки initData, описан в гайде тестирование Telegram Mini App.
Виджеты Bot API 10.4 на тестовом сервере
HTML-виджеты в сообщениях, появившиеся в Bot API 10.4, в рабочем окружении пока работают только в личном чате с ботом. Виджеты в группах, в inline-режиме и в пересланных сообщениях пока доступны только на тестовом сервере — там эти сценарии и стоит проверять. Как устроены виджеты, читайте в гайде виджеты Telegram.
Лимиты и полезные привычки
- Не устраивайте там нагрузочные тесты. Flood-лимиты в тестовом окружении не повышены и иногда даже строже. Обрабатывайте
429сretry_afterи не полагайтесь на зашитые в код значения; цифры и логика повторов — в гайде лимиты Telegram Bot API. - Разделяйте окружения в конфигурации. Храните токен и базовый адрес в отдельных переменных и пишите в лог, в каком окружении запущен бот.
- Перепроверяйте в рабочем окружении. Перед релизом прогоните те же сценарии на тестовом боте в обычном Telegram и по HTTPS: HTTP-ссылки и функции, доступные только на тестовом сервере, у реальных пользователей работать не будут.
Частые проблемы
| Симптом | Вероятная причина | Что сделать |
|---|---|---|
401 Unauthorized | Рабочий токен отправлен на /test/ или тестовый — без /test/ | Окружения разделены: токен должен соответствовать адресу (или переключателю TEST в тестере) |
400 Bad Request: chat not found | chat id взят из рабочего окружения, а таких пользователей и чатов на тестовом сервере нет | Напишите тестовому боту из тестового аккаунта и возьмите chat id из getUpdates |
| Бот не находится в поиске | Ищете из обычного аккаунта | Ищите из тестового аккаунта, в котором бот создан |
429 Too Many Requests | Flood-лимиты, которые на тестовом сервере не повышены | Подождите retry_after секунд и снизьте темп |
| Mini App по HTTP не открывается | Бот или аккаунт из рабочего окружения | Используйте бота, созданного в тестовом окружении, и открывайте его из тестового аккаунта |
Частые вопросы
Что такое тестовый сервер Telegram?
Отдельное тестовое окружение, полностью изолированное от рабочего Telegram. В нём свои аккаунты и свои боты, а запросы к Bot API идут на https://api.telegram.org/bot<token>/test/METHOD_NAME.
Как войти в тестовое окружение Telegram?
На iOS 10 раз нажмите на иконку настроек → Accounts → Login to another account → Test. В Telegram Desktop откройте ☰ Settings, зажмите Shift + Alt и кликните правой кнопкой по Add Account → Test Server. На macOS 10 кликов по иконке настроек откроют Debug Menu, затем ⌘ + клик по Add Account.
Подойдёт ли токен рабочего бота для тестового сервера?
Нет. Окружения разделены: бот, созданный в обычном Telegram, на тестовом сервере не существует, и наоборот. Создайте нового бота через @BotFather в тестовом аккаунте; токен не из того окружения обычно даёт 401 Unauthorized.
На тестовом сервере Telegram лимиты выше?
Нет. Flood-лимиты в тестовом окружении не повышены и иногда даже строже, поэтому обрабатывайте 429 Too Many Requests с retry_after и не зашивайте лимиты в код.
Можно ли открыть Mini App по HTTP в тестовом окружении?
Да. В тестовом окружении в поле url объектов WebAppInfo (Mini Apps) и LoginUrl (Web Login) допустима HTTP-ссылка без TLS. В рабочем окружении нужен HTTPS.
Обязательно ли тестировать бота на тестовом сервере?
Нет. Чаще всего хватает второго бота, созданного через @BotFather в обычном Telegram: у него свой токен, и он не мешает реальным пользователям. Тестовый сервер нужен, когда требуются HTTP-ссылки, отдельные тестовые аккаунты или функции, доступные пока только там.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов
Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.