Telegram Mini App — это обычное веб-приложение, которое открывается внутри Telegram. Интерфейс можно сделать практически как у обычного сайта или мобильного приложения: каталог, личный кабинет, форму заказа, расписание, калькулятор, игру, внутреннюю CRM или другой сценарий.
Но одного HTML-файла недостаточно, если приложение должно знать пользователя, хранить данные или взаимодействовать с Telegram-ботом. В рабочем проекте обычно участвуют несколько частей:
Telegram → бот → Mini App → backend/API → данныеНиже разберём путь от пустого бота до первого работающего Mini App и отдельно — где чаще всего допускают ошибки.
Что на самом деле представляет собой Telegram Mini App
Telegram Mini App не является отдельным типом приложения, который нужно собирать специальным конструктором Telegram.
В основе находится обычный web frontend: HTML, CSS, JavaScript или привычный frontend-стек: React, Vue, Svelte и т. д.
Telegram открывает интерфейс во встроенном WebView и передаёт дополнительные данные и методы через Telegram.WebApp. Работа с базой данных, проверка прав, заказы, расчёты и бизнес-логика обычно выполняются на backend.
Главное правило
Не переносите секреты и критическую бизнес-логику во frontend только потому, что приложение работает внутри Telegram. Код Mini App выполняется на устройстве пользователя и не должен считаться доверенной средой.
↑ К оглавлениюИз каких частей состоит Mini App
Архитектура выглядит так: Пользователь в Telegram → Telegram-бот → Telegram Mini App → Frontend → Backend / API → База данных / внешний сервис.
Небольшой информационный Mini App может почти полностью состоять из frontend. Если нужны пользователь, персональные данные, заказы, платежи, права, закрытый API или состояние, backend становится важной частью архитектуры.
↑ К оглавлениюЧто понадобится перед началом
Минимальный набор: Telegram-аккаунт, бот через BotFather, веб-приложение, публичный HTTPS URL, хостинг frontend и backend, если нужны авторизация, база данных или серверная логика. Telegram откроет внутри WebView адрес вроде https://app.example.ru/.
Как создать бота для Telegram Mini App
Если бота ещё нет, открыть @BotFather и создать нового. В результате будут username бота и bot token. Токен используется server-side частью для работы с Bot API.
Важно
Bot token нельзя помещать в JavaScript Mini App, клиентский .env, HTML, публичный репозиторий, ссылки или скриншоты. Он хранится только на сервере.
Нужно ли сначала программировать самого бота
Не обязательно делать сложного бота. Для Mini App достаточно сценария /start → сообщение → кнопка «Открыть приложение». В другом проекте бот отвечает за уведомления, команды и сообщения, а Mini App — за каталог, формы, личный кабинет и заказ.
Подробно про команды и меню Telegram-бота можно прочитать в руководстве по командам Telegram-бота.
↑ К оглавлениюКак подготовить само веб-приложение
На первом этапе Mini App можно открыть как обычную web-страницу. Подключите https://telegram.org/js/telegram-web-app.js, после чего доступны window.Telegram.WebApp и tg.ready(). Сначала добейтесь открытия приложения, доступности API и ожидаемых данных запуска, затем подключайте бизнес-логику.
Почему Mini App нужно проверять именно внутри Telegram
Обычный браузер может открыть URL, но в нём отсутствуют Telegram-контекст и WebView. Не будет нужных данных запуска, а некоторые API-методы не имеют смысла. Финальные сценарии обязательно тестируют внутри Telegram.
↑ К оглавлениюКак подключить Telegram Web Apps API
После подключения telegram-web-app.js можно получить const tg = window.Telegram.WebApp и вызвать tg.ready(). Учитывайте tg.colorScheme, tg.themeParams, tg.platform и tg.version; для новых методов сохраняйте fallback.
Как открыть Mini App из Telegram
Используются Main Mini App в профиле бота, menu button, кнопка под сообщением, keyboard button и прямая ссылка. Main Mini App настраивается через BotFather; menu button может открывать каталог, заказы или CRM; кнопка сообщения запускает приложение после нажатия. Общие возможности и сценарии также разобраны на странице про Telegram Mini App.
Прямая ссылка может выглядеть как https://t.me/example_bot?startapp или https://t.me/example_bot?startapp=product_42. Параметр запуска не доказывает личность или право доступа.
Как Mini App узнаёт пользователя
Telegram передаёт Telegram.WebApp.initData и Telegram.WebApp.initDataUnsafe. Последний удобен для отображения, но не является доверенным для авторизации.
initDataUnsafe нельзя считать доверенными данными
Frontend контролируется пользователем. Нельзя считать достоверным сообщение user.id = 123. Для идентификации используется initData и server-side проверка.
Правильная схема авторизации через initData
Поток: Telegram → Mini App получает initData → frontend отправляет её на backend → backend проверяет подпись → извлекает подтверждённого пользователя → создаёт session / token.
Backend разбирает query string с полями user, auth_date, query_id, hash, формирует data-check-string, проверяет HMAC и срок давности. Bot token остаётся только на сервере.
Что находится на frontend, а что на backend
Frontend отвечает за интерфейс, формы, отображение данных, навигацию, Telegram UI API, запросы и состояние. Backend отвечает за initData, авторизацию, права, базу, секреты, Bot API token, платежи, интеграции и расчёты.
После проверки Telegram user ID связывается с внутренним user_id и используется для заказов, профиля, подписки, корзины и настроек. Username не стоит использовать как основной уникальный идентификатор.
Отдельный backend для Mini App не обязателен: один backend может обслуживать бота, Mini App, REST/API и базу данных.
↑ К оглавлениюКак выглядит простой рабочий запуск
- создать бота;
- подготовить web-страницу;
- разместить её по HTTPS;
- подключить Web Apps API;
- открыть приложение через бота;
- проверить Telegram.WebApp;
- передать initData на backend;
- проверить пользователя сервером;
- подключить API;
- развивать интерфейс.
Что проверить перед запуском
На мобильном проверить iOS/Android, размеры, safe areas, клавиатуру, прокрутку, модальные окна, нижние кнопки, ссылки, тему, возврат назад, повторный запуск и слабое соединение.
На Desktop проверить ширину, hover/focus, touch-элементы, scrolling, keyboard navigation, закрытие Mini App и разные точки входа.
Полный backend-сценарий: открытие, авторизация, каталог, товар, заказ, сохранение в БД, ответ frontend и повторное открытие заказа. Если используется бот, проверить уведомление о заказе.
↑ К оглавлениюЧастые ошибки при создании Telegram Mini App
Mini App открывается как обычный сайт
Проверить Web Apps script, запуск через Telegram, URL, JavaScript errors и API-запросы.
Telegram.WebApp undefined
Проверить официальный script и момент обращения; обычный сайт должен учитывать отсутствие Telegram API.
Пользователь не определяется
Проверить способ запуска, initData, передачу исходной строки и server-side validation.
Backend отклоняет initData
Проверить query string, порядок полей, data-check-string, HMAC, token, hash и auth_date.
Работает в браузере, но не в Telegram
Проверять WebView, API, initData, launch method, viewport, клиентскую версию и Console/Network.
Android работает, iPhone ломается
Проверять viewport, safe area, fixed/sticky, клавиатуру, WebKit и CSS.
Какие способы запуска нужны
Не подключать всё сразу: для небольшого приложения достаточно Main Mini App + Menu Button или кнопки в сообщении + прямой ссылки.
Когда достаточно обычного бота
Для простых команд и короткого диалога Mini App может быть избыточен. Он полезнее для каталога, большого количества данных, таблиц, сложных форм, кабинета и визуализации.
Когда использовать вместе
Бот уведомляет и принимает команды, Mini App показывает каталог, историю и формы; backend и данные могут быть общими.
Короткая последовательность создания
Определить задачу; создать бота; подготовить frontend; разместить HTTPS; подключить API; настроить запуск; получить initData; выполнить validation; связать пользователя с backend; подключить API и БД; проверить mobile/desktop; пройти сценарий; настроить логи.
Если Mini App уже создан, но не запускается
Не всегда требуется переписывать приложение с нуля.
Сначала определить сбой: точка запуска → Telegram WebView → frontend → initData → backend → API → данные.
Если интерфейс открывается, но нет пользователя — одна зона диагностики. Если пользователь определяется, но не загружается каталог — другая. Если прямой URL работает, а Telegram нет — третья.
Последовательная проверка обычно быстрее полного переписывания. Если проблема относится к связке бот/backend, полезна поддержка и доработка Telegram-ботов.
Частые вопросы
Можно ли создать Telegram Mini App без бота?
Обычно Mini App связывают с Telegram-ботом: через него приложение запускается из профиля, меню, сообщения или ссылки. Само веб-приложение может открываться как обычная страница, но полноценный Telegram-сценарий обычно требует бота.
На чём можно написать Telegram Mini App?
Mini App является обычным web frontend. Его можно сделать на HTML, CSS и JavaScript или использовать привычный frontend-стек: React, Vue, Svelte и другие технологии.
Обязательно ли нужен backend?
Нет, для простого информационного приложения backend может не понадобиться. Но он нужен, если требуется авторизация, проверка initData, база данных, закрытый API, заказы, платежи или другая серверная логика.
Как Telegram Mini App узнаёт пользователя?
Telegram передаёт приложению данные запуска, включая initData. Frontend может использовать initDataUnsafe для отображения, но для доверенной идентификации исходная initData должна быть проверена на backend.
Можно ли использовать initDataUnsafe для авторизации?
Нет. initDataUnsafe контролируется клиентом и не должна считаться доказательством личности. Для server-side авторизации нужно передать исходную initData на backend и проверить её подпись с использованием bot token.
Где хранить bot token?
Только на сервере или в защищённой server-side конфигурации. Токен нельзя помещать в JavaScript Mini App, клиентский .env, HTML, публичный репозиторий, ссылки или скриншоты.
Как открыть Mini App пользователю?
Можно использовать Main Mini App в профиле бота, menu button, кнопку под сообщением, keyboard button или прямую ссылку. Для небольшого проекта обычно достаточно одной-двух понятных точек входа.
Почему Mini App работает в браузере, но не работает в Telegram?
Нужно проверить Telegram WebView, официальный Web Apps script, способ запуска, initData, URL, клиентскую версию, JavaScript errors и API-запросы. Обычный браузер не воспроизводит весь Telegram-контекст.
Если нужна разработка или диагностика Telegram Mini App
Перед началом разработки полезно определить не только внешний вид приложения, но и всю цепочку: откуда оно запускается, какие данные получает от Telegram, где проверяется пользователь, с каким API работает frontend и что хранится на backend.
Если Mini App уже существует, сначала можно проверить текущую реализацию и понять, можно ли исправить конкретный проблемный участок без переписывания проекта целиком.