Тестирование Telegram Mini App: от браузера до отладки на телефоне

Обновлено: 29 октября 2026 г. · 9 мин чтения

Тестирование Mini App удобно строить в три слоя: сначала вёрстка и логика в обычном браузере с эмуляцией Telegram.WebApp, затем запуск внутри Telegram через HTTPS-туннель с DevTools на устройстве и, наконец, проверка initData на сервере. Ниже — пошаговый план с командами и кодом, а в конце чек-лист, который закрывает классическое «в браузере работает, а в Telegram — нет».

Шаг 1. Тест Mini App в обычном браузере

Mini App — это обычная веб-страница с подключённым скриптом telegram-web-app.js. В браузере объект window.Telegram.WebApp тоже появится, но без данных: initData — пустая строка, пользователя и цветов темы нет. Поэтому сразу закладывайте запасные значения:

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
  <h1 id="hello">Загрузка…</h1>
  <script>
    const tg = window.Telegram.WebApp;
    // вне Telegram initData пустой, а initDataUnsafe.user отсутствует
    const user = tg.initDataUnsafe.user ?? { first_name: 'Тестовый пользователь' };
    document.getElementById('hello').textContent = `Привет, ${user.first_name}!`;
    document.body.style.background = tg.themeParams.bg_color || '#ffffff';
    tg.ready();
  </script>
</body>
</html>

Чтобы не писать моки вручную, откройте Mini App Tester. В обычном браузере он работает в mock-режиме: эмулирует Telegram.WebApp, показывает живую панель свойств (version, platform, colorScheme, initData, themeParams, safe areas) и лог более чем 45 событий. Так можно разобраться, как ведут себя кнопки, попапы, CloudStorage и другие API, ещё до деплоя.

Шаг 2. Как сделать Mini App в Telegram и привязать к боту

Чтобы мини-апп открывался внутри Telegram, нужны бот (как его создать — в гайде как создать бота в Telegram) и HTTPS-адрес страницы. Способы запуска:

• /newapp в @BotFather — Mini App с прямой ссылкой вида https://t.me/<bot>/<app>; параметр startapp из ссылки передаётся в приложение;
• кнопка меню бота — /setmenubutton или Bot Settings → Menu Button, а для отдельных пользователей — метод setChatMenuButton;
• Main Mini App — кнопка «Launch app» в профиле бота и ссылка https://t.me/<bot>?startapp;
• кнопки web_app в reply- и inline-клавиатурах.

Для отладки удобнее всего кнопка меню: её можно перенастроить одним запросом, не заходя в @BotFather.

curl -s -X POST "https://api.telegram.org/bot$TOKEN/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "menu_button": {
      "type": "web_app",
      "text": "Открыть приложение",
      "web_app": {"url": "https://example.trycloudflare.com"}
    }
  }'

Если передать chat_id своего личного чата с ботом, кнопка изменится только у вас — остальные пользователи продолжат видеть рабочую версию. Готовый тестер тоже можно сразу указать как URL Mini App: https://telegram-bot-api.info/telegram-mini-app-tester.html — внутри Telegram он покажет реальные данные клиента.

Шаг 3. Telegram Mini App на localhost: HTTPS-туннель

Telegram открывает Mini App только по HTTPS, а localhost вашего компьютера с телефона недоступен. Решение — туннель, который выдаёт публичный HTTPS-адрес и проксирует запросы на локальный порт:

# dev-сервер уже запущен, например Vite на порту 5173

# вариант 1: Cloudflare Quick Tunnel
cloudflared tunnel --url http://localhost:5173

# вариант 2: ngrok
ngrok http 5173

Скопируйте выданный адрес https://… и пропишите его в @BotFather или через setChatMenuButton. Несколько граблей:

• адрес бесплатного туннеля обычно меняется при каждом перезапуске — не забывайте обновлять URL у бота;
• свежие версии Vite отклоняют запросы с незнакомым заголовком Host — добавьте домен туннеля в server.allowedHosts;
• если после правок видна старая версия, закройте и заново откройте Mini App: WebView может держать страницу в кэше.

Шаг 4. Тестовая среда Telegram

У Telegram есть отдельная тестовая среда со своими аккаунтами и ботами. Главный плюс для Mini Apps — там разрешены HTTP-ссылки без TLS. Как войти:

• iOS: 10 раз нажмите на иконку настроек → Accounts → Login to another account → Test;
• Telegram Desktop: ☰ Settings → Shift+Alt+правый клик по «Add Account» → «Test Server»;
• macOS: 10 кликов по иконке настроек откроют Debug Menu, затем ⌘+клик по «Add Account».

Среда полностью отдельная: понадобятся новый аккаунт и новый бот, созданный через @BotFather уже внутри неё. Запросы к API такого бота отправляются на https://api.telegram.org/bot<token>/test/METHOD_NAME.

Шаг 5. Отладка Mini App внутри Telegram

Пункты меню иногда меняются, поэтому сверяйтесь с официальным разделом Debug Mode for Mini Apps. Если подключить DevTools не получается, откройте на устройстве Mini App Tester: он покажет version, platform, тему, safe areas и все события, которые присылает клиент.

Шаг 6. Проверка initData на сервере

Данным из initDataUnsafe доверять нельзя: их легко подменить. Передавайте на бэкенд сырую строку Telegram.WebApp.initData (например, в заголовке Authorization) и проверяйте подпись:

1. разберите строку как query string и извлеките hash;
2. соберите data_check_string: все остальные поля в виде key=value, отсортированные по ключу и соединённые символом \n (убирается только hash);
3. вычислите secret_key = HMAC_SHA256(key="WebAppData", message=bot_token);
4. данные подлинные, если hex(HMAC_SHA256(key=secret_key, message=data_check_string)) совпадает с hash;
5. проверьте свежесть auth_date, чтобы не принимать старые данные повторно.

Node.js:

import crypto from 'node:crypto';

export function validateInitData(initData, botToken, maxAgeSec = 3600) {
  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  if (!hash) return null;
  params.delete('hash');

  const dataCheckString = [...params.entries()]
    .map(([key, value]) => `${key}=${value}`)
    .sort()
    .join('\n');

  const secretKey = crypto.createHmac('sha256', 'WebAppData').update(botToken).digest();
  const expected = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest();
  const received = Buffer.from(hash, 'hex');
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) return null;

  const authDate = Number(params.get('auth_date'));
  if (!authDate || Date.now() / 1000 - authDate > maxAgeSec) return null;

  return { ...Object.fromEntries(params), user: JSON.parse(params.get('user') ?? 'null') };
}

Python:

import hashlib, hmac, json, time
from urllib.parse import parse_qsl

def validate_init_data(init_data: str, bot_token: str, max_age: int = 3600):
    data = dict(parse_qsl(init_data, keep_blank_values=True))
    received_hash = data.pop("hash", "")
    check_string = "\n".join(f"{k}={v}" for k, v in sorted(data.items()))
    secret_key = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
    expected = hmac.new(secret_key, check_string.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, received_hash):
        return None
    if time.time() - int(data.get("auth_date", 0)) > max_age:
        return None
    data["user"] = json.loads(data.get("user", "null"))
    return data

Две частые ошибки: считать подпись от строки, не декодированной из URL (значения сначала нужно раскодировать, как это делают URLSearchParams и parse_qsl), и перепутать аргументы первого HMAC — строка WebAppData служит ключом, а токен бота — сообщением.

Bot API 10.2: защита методов Mini App

Начиная с Bot API 10.2 Telegram блокирует вызовы методов Mini App со страниц, origin которых отличается от домена самого приложения. Для всех Mini Apps защита включилась автоматически 20 июля 2026 года. Отключить её можно в Mini App @BotFather, но тогда вы сами отвечаете за то, чтобы в приложении не было ссылок на недоверенные сайты. Что это значит для тестов:

• если после редиректа (OAuth, оплата на внешней странице) пользователь оказался на другом домене, методы Telegram.WebApp там не сработают — проверьте такие сценарии отдельно;
• держите все экраны, которые обращаются к API Mini App, на домене, указанном у бота;
• отключайте защиту, только если без этого никак, и тогда сами проверяйте все внешние ссылки.

Чек-лист тестирования Mini App перед релизом

• telegram-web-app.js подключён в <head> раньше остальных скриптов;
• Telegram.WebApp.ready() вызывается, как только интерфейс готов;
• цвета берутся из themeParams или CSS-переменных --tg-theme-*, проверены светлая и тёмная темы;
• в полноэкранном режиме учтены safeAreaInset и contentSafeAreaInset;
• новые функции обёрнуты в проверку isVersionAtLeast() — у пользователей бывают старые клиенты;
• initData проверяется на сервере, включая auth_date;
• все страницы с вызовами API работают на одном HTTPS-домене;
• приложение проверено на iOS, Android и Desktop.

Дальше пригодятся гайды как получить токен бота (он нужен для проверки initData) и что нового в Bot API 10.3. Кнопку меню с адресом вашего Mini App можно настроить прямо в браузере: setChatMenuButton в Bot API Tester.