Тестовий сервер 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
Найшвидший спосіб протестувати телеграм-бота, не заважаючи його користувачам, — запустити другу копію коду на іншому боті:
- Створіть нового бота командою
/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. Увесь процес тестування міні-застосунку, від 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через 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.