Telegram Bot API

Тестовый сервер Telegram: как тестировать бота в тестовом окружении

· 7 мин чтения

Тестовый сервер 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-бота, не мешая его пользователям, — запустить вторую копию кода на другом боте:

  1. Создайте нового бота командой /newbot в @BotFather (подробно — в гайде как создать бота в Telegram).
  2. Пропишите его токен в конфигурацию тестового экземпляра, например в отдельный файл .env.
  3. Отлаживайте всё на новом боте — рабочий бот продолжает работать как раньше.

Есть нюанс: 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 можно из официальных приложений:

Тестовый аккаунт добавляется рядом с обычным, так что переключаться между окружениями можно в одном приложении. Всё, что вы делаете в тестовом аккаунте, включая переписку с тестовым ботом, остаётся в тестовом окружении.

Создайте бота на тестовом сервере и получите токен

В тестовом аккаунте откройте @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 умеет отправлять запросы в тестовое окружение без единой строки кода:

  1. Откройте getMe в Bot API Tester.
  2. Нажмите переключатель TEST рядом с полем токена или откройте страницу тестера с ?env=test в адресе.
  3. Вставьте токен тестового бота и нажмите 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.

Лимиты и полезные привычки

Частые проблемы

СимптомВероятная причинаЧто сделать
401 UnauthorizedРабочий токен отправлен на /test/ или тестовый — без /test/Окружения разделены: токен должен соответствовать адресу (или переключателю TEST в тестере)
400 Bad Request: chat not foundchat id взят из рабочего окружения, а таких пользователей и чатов на тестовом сервере нетНапишите тестовому боту из тестового аккаунта и возьмите chat id из getUpdates
Бот не находится в поискеИщете из обычного аккаунтаИщите из тестового аккаунта, в котором бот создан
429 Too Many RequestsFlood-лимиты, которые на тестовом сервере не повышеныПодождите 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.