Сначала уточняем, что именно не открывается
Разделите три ситуации: Telegram вообще не открывает окно, окно появляется без содержимого, интерфейс виден, но данные или вход не работают. У них разные причины. Запишите время, версию Telegram, платформу, способ запуска, адрес приложения без секретных параметров и версию вашей сборки.
Повторите запуск одним и тем же способом с тестового аккаунта. Для сравнения используйте ещё один клиент и другую сеть. Если ошибка есть только в одном окружении, это направление поиска, а не доказательство ошибки Telegram. Начните с собственного адреса, ресурсов и JavaScript.
Не просите пользователя прислать полный initData или ссылку с авторизационными данными. Для диагностики достаточно безопасного request ID и категории ошибки. Снимок экрана также может содержать личные сведения: обрежьте их до передачи в рабочий чат.
Проверяем адрес и HTTPS снаружи
Откройте точный URL приложения на устройстве пользователя в обычном браузере. Он должен возвращать нужную страницу без предупреждения сертификата, страницы хостинга, Basic Auth или проверки, требующей ручного прохождения. Успешный запрос с самого сервера не доказывает доступность для телефона.
Следующая команда выполняет GET и показывает заголовки, проверяя сертификат штатным способом. Замените адрес на публичную страницу без токенов. Это Bash; в PowerShell используйте curl.exe вместо псевдонима curl.
curl --connect-timeout 5 --max-time 15 -sS -D - -o /dev/null \ https://mini.example.com/
При ошибке DNS проверьте записи домена и доступность из нужной сети. При ошибке TLS — имя сертификата, срок и цепочку на веб-сервере. Не используйте -k как исправление: отключение проверки у диагностического клиента не исправляет Telegram.
Если ответ 301/302, проверьте Location и всю цепочку переходов до конечного HTTPS-адреса. Если 401/403 — выясните, не блокируют ли страницу авторизация, WAF или региональные правила. Если 404 — сверяйте путь, включая завершающий слеш и базовый каталог приложения. Если 200 — откройте тело ответа: код статуса не отличает вашу страницу от HTML-заглушки.
Проверяем HTML, CSS и JavaScript
В браузерных инструментах разработчика откройте Network и перезагрузите страницу. Найдите основной документ, JavaScript, CSS и первый API-запрос. Если документ загружается, а скрипт возвращает 404, сравните URL файла с опубликованной сборкой. Частая причина — новый HTML ссылается на хешированный файл, который ещё не загружен или уже удалён.
При ошибке MIME посмотрите тело ресурса: вместо JavaScript сервер мог вернуть HTML главной страницы через универсальный fallback. Исправьте маршрутизацию статических файлов и Content-Type. Проверяйте также относительные пути при открытии вложенного URL, а не только корня сайта.
Если проблема появилась после релиза, сопоставьте HTML, manifest и ресурсы одной версии. Проверьте CDN, браузерный кэш и service worker, если он используется. Очистка кэша на своём телефоне полезна как эксперимент, но не исправляет несовместимую выкладку для остальных пользователей.
HTTPS-страница не должна загружать обязательные скрипты или API через HTTP. Mixed content, блокировки Content Security Policy и недоступность внешнего CDN отображаются в Console/Network. Разрешайте только нужные источники; не отключайте всю CSP для устранения одного заблокированного ресурса.
Находим первую ошибку и показываем понятный экран
В Console ищите первую ошибку до каскада последующих. Если не определён Telegram.WebApp, проверьте загрузку официального скрипта и порядок выполнения. Если падает импорт модуля — сначала исправьте путь или синтаксис. Если ошибка возникает на обращении к данным пользователя, проверьте наличие полей и способ запуска.
Ниже диагностическая оболочка для отдельной тестовой страницы. Она показывает, загрузился ли документ, и сообщает о сбое запуска без вывода чувствительных объектов. Замените /app.js на модуль вашей страницы; это не полный Mini App и не обход серверной авторизации.
<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Проверка запуска</title>
</head>
<body>
<p id="boot" role="status">HTML загружен. Запускаем интерфейс…</p>
<noscript>Для этой страницы необходим JavaScript.</noscript>
<script>
const boot = document.getElementById('boot');
window.addEventListener('error', () => {
boot.textContent = 'Ошибка запуска. Передайте поддержке время и версию приложения.';
});
window.addEventListener('unhandledrejection', () => {
boot.textContent = 'Не удалось завершить загрузку. Попробуйте повторить позже.';
});
</script>
<script src="https://telegram.org/js/telegram-web-app.js?64"></script>
<script type="module">
try {
const app = window.Telegram?.WebApp;
if (!app) throw new Error('Telegram bridge unavailable');
const module = await import('/app.js');
await module.mount();
app.ready();
boot.textContent = 'Интерфейс готов';
} catch (error) {
boot.textContent = 'Интерфейс не запустился. Проверьте загрузку ресурсов.';
}
</script>
</body>
</html>
mount должен построить основные элементы экрана и показать отдельное состояние ожидания данных. Не заставляйте его бесконечно ждать CRM перед ready(). Метод ready сообщает Telegram о готовности интерфейса; он не проверяет токен и не исправляет упавший JavaScript. Если CSP запрещает inline-скрипты, вынесите обработчики в разрешённый файл или используйте предусмотренный вашей политикой nonce.
Сверяем способ запуска и авторизацию
Проверьте URL в кнопке сообщения, персональной и общей кнопке меню, а также в Main Mini App, если этот способ используется. Один старый URL может остаться только у части пользователей. getChatMenuButton позволяет сверить кнопку конкретного личного чата; корректный общий адрес не доказывает, что персональная настройка совпадает.
Открытие страницы напрямую во внешнем браузере проверяет отображение, но не воспроизводит запуск из Telegram. Отсутствующий initData в таком запуске не следует заменять произвольным user_id. Разные способы открытия дают разный контекст; например, sendData не является универсальной отправкой для любой Mini App.
Если HTML и скрипты загрузились, а сервер возвращает 401, проверьте подпись initData, токен бота и auth_date. При 419 проверьте CSRF и cookie-сессию. При CORS-ошибке сравните фактические origin страницы и API; настройте разрешённый origin и credentials по выбранной схеме, вместо Access-Control-Allow-Origin: * для сессий.
Проверяем различия клиентов и темы
Сравните актуальные мобильный и настольный Telegram и, если он нужен аудитории, Telegram Web. Проверьте поддерживаемые методы JavaScript API перед вызовом и предусмотрите запасное поведение. Если приложение использует новый API без проверки версии, старый клиент может остановить весь запуск.
Проверьте светлую и тёмную темы: белый текст на белом фоне иногда выглядит как пустая страница. Осмотрите размеры корневого контейнера, перекрывающий слой загрузки, скролл и экранную клавиатуру. Загруженный DOM с нулевой высотой — другая проблема, чем отсутствующий HTML.
Для Web отдельно учитывайте размещение в браузере и ограничения cookie. Для мобильного устройства используйте доступные для его платформы средства отладки; не рассчитывайте, что инструменты настольного браузера автоматически показывают внутренний webview телефона.
Проверяем исправление и границы BotGate
Повторите тот же запуск, в той же сети и клиенте, где возникал сбой. Затем проверьте второй клиент и холодную загрузку. Успех означает, что виден интерфейс, завершился вход, прошёл запрос данных и пользователь получил понятный результат. Один HTTP 200 или вызов ready не подтверждают весь сценарий.
Если BotGate используется для отправки сообщений, он обслуживает серверные вызовы Bot API. HTML, ресурсы, сессия и API вашей формы проверяются отдельно. Если форма сохранилась, но уведомление не пришло, переходите к диагностике исходящих запросов.
Telegram Mini Apps — инициализация, способы запуска и API клиента.
CORS — ограничения запросов между origin.