Telegram Mini App не открывается: как найти причину

# Telegram Mini App не открывается: как найти причину

Telegram Mini App может нормально работать в обычном браузере, но не запускаться внутри Telegram, зависать на загрузке или показывать белый экран.

Причина не обязательно находится в самом Telegram.

Проблема может быть в:

• URL Mini App;
• HTTPS;
• настройках бота;
• способе запуска;
• JavaScript;
• загрузке telegram-web-app.js;
• backend/API;
• CORS;
• несовместимой функции Web API;
• конкретном клиенте Telegram;
• iOS или Android;
• обработке параметров запуска;
• ошибке, которая возникает только внутри WebView.

Поэтому первым делом нужно определить: Mini App вообще не запускается или запускается, но уже внутри ломается само веб-приложение.

Сначала определите точный симптом

Проверьте, что именно видит пользователь.

Например:

нажал кнопку
↓
ничего не произошло

или:

Mini App открылся
↓
вечная загрузка

или:

Mini App открылся
↓
белый экран

или:

в браузере работает
↓
в Telegram не открывается

или:

Android → работает
iPhone → не работает

Это разные неисправности.

Если окно Mini App даже не появляется, сначала исследуйте кнопку, ссылку и настройки запуска.

Если Telegram WebView уже открылся, но внутри пустая страница, гораздо важнее JavaScript, Network и frontend/backend приложения.

Проверьте сам URL Mini App

Сначала откройте тот же HTTPS URL обычным браузером.

Если он уже там возвращает:

404

500

ошибку TLS или бесконечный redirect, Telegram это не исправит.

Для WebAppInfo Telegram Bot API требует именно HTTPS URL.

Проверьте:

• HTTP status;
• сертификат;
• срок действия сертификата;
• DNS;
• redirects;
• доступность с внешней сети;
• загрузку HTML;
• загрузку JavaScript и CSS.

Не начинайте менять BotFather, если исходная страница сама недоступна.

Не проверяйте только главную страницу домена

Допустим, Mini App настроен на:

https://example.com/app/

То, что:

https://example.com/

открывается нормально, ещё ничего не доказывает.

Проверяйте именно фактический URL Mini App.

Особенно после deploy:

• мог измениться route;
• каталог мог исчезнуть;
• SPA fallback мог перестать работать;
• сервер мог вернуть 404 на вложенный путь.

Определите, каким способом запускается Mini App

Это очень важно.

Telegram сейчас поддерживает несколько разных способов запуска Mini Apps, включая:

• Main Mini App из профиля бота;
• keyboard button;
• inline button;
• menu button;
• inline mode;
• direct link;
• attachment menu.

Один и тот же Mini App стоит проверить через тот способ, которым реально пользуется пользователь.

Например:

профиль бота → работает
кнопка в сообщении → не работает

уже говорит, что само приложение, вероятно, доступно, а проблема связана с конкретной точкой запуска или её настройкой.

Если не работает кнопка запуска

Проверьте фактический объект кнопки, который отправляет бот.

Для Web App Telegram использует поле:

web_app

с WebAppInfo.

URL внутри него должен быть корректным HTTPS URL. Для некоторых типов web_app-кнопок Bot API также ограничивает контекст использования — например, keyboard/inline Web App имеет правила для приватного чата с ботом.

Поэтому не ограничивайтесь проверкой:

кнопка визуально есть.

Проверьте, что бот реально отправил правильный тип кнопки и правильный URL.

Проверьте Main Mini App в BotFather

Если приложение должно открываться кнопкой из профиля бота, проверьте конфигурацию Main Mini App в @BotFather.

Telegram описывает этот сценарий отдельно: после настройки Main Mini App на странице профиля бота появляется кнопка запуска приложения.

Если после переноса приложения URL изменился, а BotFather продолжает хранить старый адрес, пользователь будет запускать старую точку входа.

Проверьте:

BotFather URL
=
реальный production URL

Проверьте direct link

Для Main Mini App Telegram поддерживает ссылки вида:

https://t.me/botusername?startapp

и:

https://t.me/botusername?startapp=command

Для именованных Mini Apps используются также соответствующие t.me-ссылки приложения. Параметр startapp передаётся внутрь Mini App как start_param и tgWebAppStartParam.

Если Mini App открывается без параметра:

?startapp

но ломается с:

?startapp=product-42

проверяйте уже обработку параметра запуска.

Не нужно в таком случае менять HTTPS или Telegram WebApp SDK.

Проверьте telegram-web-app.js

Для подключения Mini App к Telegram клиенту официальная документация предлагает загрузить:

<script src="https://telegram.org/js/telegram-web-app.js?63"></script>

в <head> до других скриптов, которым нужен Telegram WebApp API.

После загрузки становится доступен:

window.Telegram.WebApp

Если приложение сразу выполняет:

Telegram.WebApp.ready()

или обращается к:

Telegram.WebApp.initData

до загрузки Telegram script, возможна JavaScript-ошибка ещё до нормального рендера интерфейса.

Проверьте реальный порядок загрузки.

Не оставляйте белый экран без диагностики

Белый экран обычно означает не:

Telegram ничего не показывает,

а:

HTML загрузился, но приложение не смогло отрисоваться.

Первым делом нужны:

• JavaScript console;
• Network;
• failed requests;
• stack trace;
• response API.

Ищите:

Uncaught ...

ReferenceError

TypeError

Failed to fetch

CORS

401

403

500

Одна конкретная ошибка полезнее десяти изменений конфигурации.

Проверьте начальную загрузку приложения

Очень распространённая архитектура:

HTML
↓
JavaScript
↓
API request
↓
данные пользователя
↓
render

Если API-запрос упал, а frontend не показывает нормальное состояние ошибки, пользователь увидит просто вечный loader или пустой экран.

Поэтому проверьте отдельно:

1. загрузился ли HTML;
2. запустился ли JS;
3. появился ли Telegram.WebApp;
4. отправился ли запрос backend;
5. какой response пришёл;
6. дошёл ли код до render.

Не называйте такую проблему «Telegram не открывает Mini App», пока не локализован фактический этап.

Вызывайте ready() в правильный момент

Telegram предоставляет:

Telegram.WebApp.ready()

Этот метод сообщает клиенту Telegram, что основные элементы интерфейса готовы и loading placeholder можно убрать.

Telegram рекомендует вызывать его достаточно рано после загрузки необходимых элементов. Если ready() не вызвать, placeholder скрывается только после полной загрузки страницы.

Но ready() не чинит сломанное приложение.

Если JavaScript падает раньше, нужно исправлять ошибку, а не просто добавлять ready() в случайное место.

Проверьте версию Telegram WebApp API

Новые возможности Mini Apps появляются постепенно.

Telegram предоставляет:

Telegram.WebApp.version

и:

Telegram.WebApp.isVersionAtLeast(...)

чтобы приложение могло определить доступный уровень API.

Если код без проверки вызывает функцию, которой нет в старом клиенте Telegram, результат может отличаться на разных устройствах.

Например, правильнее строить логику как:

const tg = window.Telegram?.WebApp;

if (tg?.isVersionAtLeast('8.0')) {
  // функция для поддерживаемого клиента
}

а не предполагать, что любой установленный Telegram поддерживает весь текущий Mini Apps API.

Запишите platform и version

Для платформенных ошибок полезно логировать:

const tg = window.Telegram?.WebApp;

console.log({
  platform: tg?.platform,
  version: tg?.version
});

Telegram официально предоставляет оба поля.

Так вместо сообщения:

на одном телефоне не работает

вы получите, например:

platform: ios
version: ...

и сможете сравнить с рабочим устройством.

Отдельно проверьте iPhone

В Wordstat у нашего общего запроса есть конкретный DEEP_CHILD:

telegram ios 18 не открывается mini app — 7.

Его имеет смысл включить в диагностику, но не нужно заранее считать, что в iOS 18 существует универсальный баг Telegram Mini Apps.

Правильная проверка:

тот же пользователь
тот же бот
тот же Mini App URL

сравнить на:

• iPhone;
• Android;
• Telegram Desktop.

Если:

Android → работает
Desktop → работает
iPhone → не работает

тогда уже есть подтверждённая platform-specific область проблемы.

Если проблема только на iOS

Не начинайте с полного переписывания Mini App.

Сначала сравните:

• версию Telegram;
• iOS;
• WebApp platform;
• WebApp version;
• JavaScript errors;
• network requests;
• CSS/layout;
• используемые browser APIs;
• доступность конкретных Telegram API methods.

Особенно важно понять:

Mini App не загружается вообще

или:

Mini App загружается, но интерфейс оказывается невидимым или сломанным.

Это разные вещи.

Не путайте layout-проблему с ошибкой запуска

На мобильных устройствах содержимое Mini App находится внутри Telegram WebView.

Telegram предоставляет данные о:

• viewportHeight;
• viewportStableHeight;
• safe area;
• content safe area.

Документация отдельно рекомендует учитывать safe areas, особенно в fullscreen-режиме.

Поэтому сценарий:

окно открылось
но кнопка/контент вне видимой области

не является настоящей ошибкой запуска.

Проверьте layout.

Особенно:

height: 100vh;

фиксированные панели и абсолютное позиционирование.

В Mini App лучше учитывать реальные viewport-параметры Telegram, а не предполагать, что WebView идентичен обычному Safari или Chrome.

Проверьте CSS safe area

Особенно на iPhone интерфейс может пересекаться:

• с верхними control elements;
• нижней системной зоной;
• Telegram UI.

Telegram сейчас предоставляет отдельные safe-area данные и CSS variables для Mini Apps.

Если приложение технически открылось, но пользователь видит только фон или не может нажать основную кнопку, проверьте геометрию интерфейса до диагностики backend.

Если работает в Safari, но не в Telegram

Это сильный диагностический сигнал.

Обычный браузер и Telegram WebView — не один и тот же контекст.

Сравните:

Safari/Chrome
vs
Telegram WebView

по:

• URL;
• cookies;
• local storage;
• request headers;
• Web API;
• JavaScript;
• авторизации;
• CORS;
• параметрам Telegram.

Не делайте вывод:

раз Chrome открыл, frontend исправен полностью.

Он подтвердил только работу в Chrome.

Проверьте backend-запросы

Mini App может открыть HTML, но затем обращаться к:

https://api.example.com/...

Если backend:

• недоступен;
• возвращает 401;
• отвергает Origin;
• не принимает Telegram init data;
• выдаёт 500,

frontend может остаться пустым.

Проверьте Network и server logs одновременно.

Правильная цепочка:

клик
↓
WebView
↓
HTML
↓
JS
↓
API
↓
response
↓
render

Найдите первый сломанный шаг.

Не доверяйте initDataUnsafe на сервере

Если Mini App использует данные пользователя для запуска, Telegram отдельно предупреждает: данные из:

Telegram.WebApp.initDataUnsafe

нельзя считать доверенными.

Для backend нужно передавать исходное:

Telegram.WebApp.initData

и валидировать его на сервере.

Если сервер отвергает init data, Mini App может визуально выглядеть как «не открывается», хотя на самом деле frontend уже загружен, а backend вернул ошибку авторизации.

Проверяйте HTTP response.

Не подменяйте initData обычными URL-параметрами

Если приложение ожидает Telegram user из initData, а frontend запущен просто в браузере, Telegram-контекста там может не быть.

Поэтому тест:

открыл URL напрямую в Chrome

и:

открыл Mini App через Telegram

не всегда должны давать идентичный auth flow.

Хорошее приложение должно явно обрабатывать оба сценария или хотя бы показывать понятную ошибку, а не белый экран.

Проверьте способ запуска перед использованием sendData

Telegram.WebApp:

sendData(...)

доступен не для любого сценария Mini App.

Официальная документация указывает, что этот метод предназначен для Mini Apps, запущенных через keyboard button; он отправляет web_app_data обратно боту и закрывает Mini App.

Поэтому если приложение:

• открывается нормально;
• но при нажатии финальной кнопки «ничего не происходит»,

проверьте не только код sendData, но и как Mini App был запущен.

Это уже не ошибка открытия, но часто выглядит для пользователя как «Mini App не работает».

Проверьте startapp

Если логика приложения зависит от:

startapp

проверьте фактическое значение:

Telegram.WebApp.initDataUnsafe?.start_param

и:

tgWebAppStartParam

Telegram передаёт start parameter именно для соответствующих способов запуска.

Если код ожидает:

product_123

а получает:

undefined

и затем падает — исправлять нужно обработку параметра, а не Telegram.

Не падайте на отсутствующем параметре

Плохой вариант:

const id = startParam.split('_')[1];

если startParam иногда отсутствует.

Лучше сначала проверить:

if (!startParam) {
  // показать нормальное состояние или fallback
}

Telegram Mini App должен переживать допустимые варианты запуска без белого экрана.

Проверьте редиректы

Особенно подозрительна цепочка:

Mini App URL
↓
302
↓
login
↓
302
↓
Mini App URL

или:

https://app.example.com
↓
http://app.example.com
↓
https://app.example.com

Проверьте полную redirect chain.

Обычный браузер может скрыть проблему благодаря старым cookies или кешу, а WebView покажет её сразу.

Проверьте авторизацию отдельно

Не связывайте в один шаг:

Mini App открылся?

и:

пользователь авторизован?

Сначала должен загрузиться интерфейс.

Потом отдельно:

• получены ли Telegram data;
• прошла ли серверная validation;
• создана ли session;
• отдал ли backend user profile.

Если auth не прошёл, пользователь должен увидеть ошибку авторизации, а не пустой экран.

Проверьте CSP

Если сайт использует Content Security Policy, убедитесь, что она не блокирует необходимые ресурсы приложения.

Например:

• Telegram script;
• собственный JS;
• API;
• изображения;
• WebSocket.

В Console при такой проблеме обычно будет явное CSP violation.

Не отключайте CSP целиком только ради теста.

Лучше определить конкретный заблокированный resource.

Проверьте CORS

CORS имеет смысл проверять тогда, когда frontend Mini App действительно обращается к другому origin.

Например:

app.example.com
→
api.example.net

Если Network показывает blocked request, проверяйте server response headers.

Не добавляйте:

Access-Control-Allow-Origin: *

наугад, особенно если запросы используют credentials или чувствительные данные.

Если Mini App перестал открываться после deploy

Очень полезный сценарий:

старая версия → работала
deploy
новая версия → не работает

Сравните:

• HTML;
• JS bundle;
• environment variables;
• API URL;
• routes;
• CSP;
• build assets;
• service worker;
• server response.

Не начинайте обновлять Telegram на всех устройствах, пока есть столь сильная связь с deploy.

Если перестал работать после обновления Telegram

Тогда сравните несколько клиентов.

Зафиксируйте:

Telegram version
platform
WebApp version

и проверьте тот же Mini App на другом клиенте.

Telegram API позволяет определить доступную версию и проверять поддержку конкретных возможностей через isVersionAtLeast().

Если код зависит от новой или платформенной функции, предусмотрите fallback.

Не определяйте всё только по User-Agent

Telegram уже предоставляет:

Telegram.WebApp.platform

поэтому для Telegram-specific ветвления лучше сначала использовать официальный WebApp context.

Для Android Telegram также добавляет дополнительные сведения о клиенте и устройстве в User-Agent, но это скорее дополнительная диагностика, а не замена feature detection.

Проверяйте поддержку функции, а не название телефона

Лучший подход:

поддерживается функция?

хуже:

это iPhone → значит делаем другой код

Если Telegram даёт возможность проверить версию API или конкретный объект, используйте это.

Так приложение меньше ломается после обновления устройств и клиентов.

Если проблема возникает только у одного пользователя

Сравните:

• тот же URL у другого пользователя;
• другой Telegram account;
• другую сеть;
• другую платформу;
• версию Telegram.

Если 99 пользователей открывают Mini App, а один нет, глобальная недоступность сервера становится менее вероятной.

Но не списывайте проблему сразу на пользователя.

Нужно найти воспроизводимое отличие.

Если не работает у всех

Тогда начинать лучше с общей инфраструктуры:

1. URL;
2. HTTPS;
3. DNS;
4. frontend response;
5. JS;
6. backend;
7. настройки BotFather / кнопки.

Не тратьте время сначала на уникальные особенности iOS.

Добавьте диагностическое логирование

Для Mini App полезно сохранять хотя бы:

timestamp
platform
Telegram WebApp version
launch source
start parameter
frontend build version
API response status

без записи секретных данных.

Тогда сообщение пользователя:

не открывается

можно сопоставить с конкретной попыткой запуска.

Не логируйте initData и токены как обычный debug

initData используется для подтверждения данных пользователя и не должен бесконтрольно попадать в публичные логи.

То же относится к:

• bot token;
• cookies;
• Authorization headers;
• session secrets.

Для диагностики достаточно безопасных признаков:

initData present: yes/no
validation: pass/fail

без публикации исходных секретов.

Короткий порядок диагностики

Если Telegram Mini App не открывается:

1. зафиксировать точный способ запуска;
2. открыть фактический Mini App URL;
3. проверить HTTPS и redirects;
4. проверить кнопку или BotFather configuration;
5. убедиться, что Telegram WebApp script загрузился;
6. проверить JavaScript Console;
7. проверить Network;
8. определить, появился ли window.Telegram.WebApp;
9. записать platform и version;
10. проверить backend/API;
11. проверить initData validation;
12. сравнить iOS, Android и Desktop;
13. если проблема только на одной платформе — локализовать platform-specific код;
14. проверить поддержку используемых Telegram APIs;
15. исправить конкретный сломанный этап;
16. повторить запуск тем же способом.

Чего не стоит делать

Если Telegram Mini App не открывается, не стоит сразу:

• создавать нового бота;
• менять bot token;
• переписывать весь frontend;
• отключать HTTPS;
• отключать CORS и CSP целиком;
• считать любой белый экран багом Telegram;
• считать iOS 18 причиной только по одному сообщению пользователя;
• менять BotFather и frontend одновременно;
• обновлять все зависимости без диагностики;
• доверять initDataUnsafe на backend;
• вызывать новые API без проверки поддержки;
• тестировать только обычным браузером.

Сначала нужно определить уровень:

точка запуска
↓
Telegram WebView
↓
HTTPS / HTML
↓
JavaScript
↓
Telegram WebApp API
↓
backend
↓
render

и найти первый шаг, где поведение отличается от рабочего сценария.