DeveloctopusМатериал для CTO и владельцев продукта, которые планируют разработку Telegram Mini App и хотят понимать, из чего она на самом деле состоит. Разбираем архитектуру, проверку данных пользователя на сервере, адаптацию под клиент Telegram, платежи, админку и запуск через BotFather — то, что не видно в макетах, но определяет сроки и надежность.
Из чего состоит система
Частая ошибка на старте — считать Mini App «просто фронтендом». На деле это минимум четыре части, и у каждой своя зона ответственности:
| Компонент | Что делает | На что обратить внимание |
|---|---|---|
| Фронтенд | Интерфейс, который Telegram открывает во встроенном окне | Вес бандла, тема, viewport, системные кнопки |
| Бэкенд API | Бизнес-логика, база данных, интеграции | Проверка initData, права доступа, идемпотентность |
| Бот | Точка входа, уведомления, прием платежных событий | Webhook, очередь отправки, разрешение на сообщения |
| Админ-панель | Работа менеджеров с заказами, контентом, пользователями | Роли, журнал действий, выгрузки |
Если хотя бы одна часть сделана на скорую руку, это всплывает в эксплуатации: заказы теряются между ботом и CRM, менеджеры правят цены в базе руками, а уведомления приходят с опозданием.
Фронтенд: стек и работа с API Telegram
Для интерфейса подходит любой современный стек для одностраничных приложений: React, Vue, Svelte со сборкой на Vite. Мы обычно берем то, что команда заказчика сможет поддерживать после передачи проекта. Важнее фреймворка другое: приложение открывают из чата, часто по мобильному интернету, поэтому первый экран должен грузиться быстро. Делите код по маршрутам, сжимайте изображения, не тяните тяжелые библиотеки ради одной функции.
Связь с Telegram идет через скрипт telegram-web-app.js и объект Telegram.WebApp. Через него приложение сообщает о готовности (ready), разворачивается на всю высоту (expand), управляет основной кнопкой внизу экрана (MainButton) и кнопкой «Назад» (BackButton), вызывает вибрацию и системные попапы. Кнопку «Назад» нужно синхронизировать с собственной историей роутера, иначе пользователь закроет приложение, когда хотел вернуться на шаг.
Тема и viewport
Telegram передает цвета текущей темы в themeParams и в CSS-переменные вида --tg-theme-bg-color. Если строить стили на них, приложение само выглядит уместно в светлой и темной теме, а при смене темы приходит событие themeChanged.
С высотой экрана сложнее. Окно может быть свернуто наполовину, раскрываться жестом, сжиматься при открытии клавиатуры. Для этого есть viewportHeight и viewportStableHeight, событие viewportChanged и переменная --tg-viewport-stable-height. Привычная верстка «на всю высоту экрана» здесь ломается: основную кнопку или поле ввода может перекрыть. В полноэкранном режиме дополнительно учитывайте безопасные зоны — отступы под вырез камеры и элементы Telegram.
Авторизация: проверка initData на сервере
При запуске Telegram передает приложению строку initData: данные пользователя, время авторизации auth_date, параметр запуска и подпись hash. Есть и уже разобранный объект initDataUnsafe, но, как следует из названия, доверять ему нельзя — любой может открыть ваш фронтенд в браузере и подставить чужой ID. Источник истины — только проверка на сервере:
- Фронтенд отправляет на бэкенд строку Telegram.WebApp.initData целиком, например в заголовке запроса.
- Сервер разбирает ее как query string и отделяет поле hash.
- Остальные поля сортирует по ключу и склеивает в строку вида key=value через перевод строки.
- Вычисляет секретный ключ: HMAC-SHA256 от токена бота, где ключом служит строка WebAppData.
- Считает HMAC-SHA256 от строки из шага 3 этим секретным ключом и сравнивает результат в hex с hash — функцией сравнения, устойчивой к атакам по времени.
- Проверяет auth_date и отклоняет слишком старые данные.
Сессии и идентификация
После успешной проверки есть два рабочих варианта: проверять initData на каждый запрос (это дешево) или выдать собственный короткоживущий токен сессии. Пользователя в базе привязывайте к числовому user.id, а не к username — имя пользователя может смениться или отсутствовать. Сессии на cookies лучше не строить: в веб-версии Telegram мини-приложение открывается во фрейме, и браузер может блокировать такие cookies.
Бэкенд, бот и интеграции
Бэкенд — обычное API (REST или GraphQL) поверх базы данных; для большинства проектов хватает PostgreSQL. Отдельно стоит продумать несколько вещей, специфичных для Telegram:
- Параметр запуска. В прямую ссылку можно добавить startapp, и он придет в initData как start_param. Так передают метку рекламного канала, реферальный код или ID товара, на который нужно сразу открыть приложение.
- Уведомления через очередь. У Bot API есть ограничения на частоту отправки, поэтому массовые сообщения отправляют через очередь с повторами, а не циклом в обработчике запроса.
- Разрешение на сообщения. Если человек открыл приложение по ссылке и ни разу не запускал бота, писать ему бот не сможет, пока пользователь не разрешит это. Запросить разрешение можно прямо из Mini App.
- Интеграции. Заказы и заявки уходят в CRM и 1С через фоновые задачи с повторными попытками, чтобы сбой внешней системы не ломал оформление. Подробнее — в статье про интеграцию с amoCRM и Битрикс24.
Платежи
Схема оплаты зависит от того, что вы продаете. Физические товары и услуги оплачивают через платежного провайдера, подключенного к боту: бэкенд создает ссылку на счет методом createInvoiceLink, фронтенд открывает ее через openInvoice, а бот получает pre_checkout_query (на него нужно успеть ответить) и итоговое сообщение об успешной оплате. Цифровые товары и услуги внутри Telegram оплачиваются в Telegram Stars.
Ключевое правило: факт оплаты подтверждает сервер по событию от Telegram или провайдера, а не фронтенд по закрытию окна. Иначе заказ можно «оплатить», просто закрыв попап. Детали по провайдерам, Stars и чекам — в материале о приеме оплаты в Telegram.
Админ-панель и эксплуатация
Менеджерам нужен инструмент, иначе любая правка превращается в задачу для разработчика. Минимальный набор админки:
- заказы или заявки со статусами, поиском и фильтрами;
- редактирование каталога, цен, расписания или другого контента;
- карточка пользователя с историей действий;
- отправка сообщений сегментам пользователей;
- роли сотрудников и журнал изменений.
Админку обычно делают отдельным веб-интерфейсом. Для небольших команд часть функций иногда выносят в тот же бот — например, менеджер меняет статус заказа кнопкой в служебном чате. Плюс к этому — сбор ошибок фронтенда, логи запросов к API и мониторинг доступности: Mini App работает внутри чужого клиента, и без этих данных воспроизвести баг у пользователя почти невозможно.
Хостинг, тестирование и запуск
Мини-приложение должно открываться по HTTPS с валидным сертификатом. Статику удобно раздавать через CDN, API держать на отдельном домене или пути. Для разработки заводите отдельного тестового бота со своим токеном и стендом — так эксперименты не задевают реальных пользователей.
Тестировать нужно на реальных устройствах: iPhone, несколько Android-смартфонов разного класса и десктопный Telegram. Для отладки в настройках клиентов Telegram можно включить режим отладки WebView и подключиться инструментами разработчика браузера — порядок действий для каждой платформы описан в официальной документации.
Сам запуск выглядит так:
- Создать бота в BotFather и получить токен.
- Задеплоить фронтенд и API, настроить webhook бота.
- Настроить кнопку меню с адресом приложения и при необходимости создать прямую ссылку командой /newapp.
- Подключить платежного провайдера, если нужны оплаты.
- Пройти сценарии на устройствах, проверить отказ при поддельной initData.
- Открыть доступ сначала небольшой группе, затем всем.
Если задача — быстро проверить спрос, а не строить полную систему, посмотрите, как собрать MVP Mini App за 2–4 недели.
Частые вопросы
Сколько времени занимает разработка Mini App?
Первую версию с одним сценарием можно запустить от 2 недель. Проект с оплатой, интеграцией с 1С или CRM и полноценной админкой занимает больше — срок считаем после брифа.
Можно ли использовать наш существующий бэкенд?
Да, если у него есть API. Обычно добавляем эндпоинт проверки initData, привязку пользователя к Telegram ID и обработку событий бота, остальная логика остается вашей.
Как защитить API от запросов не из Telegram?
Каждый запрос должен нести initData или выданный после ее проверки токен. Плюс стандартные меры: ограничение частоты запросов и проверка прав на каждый объект, а не только факта авторизации.
Сколько стоит разработка Telegram Mini App?
Telegram-боты и Mini Apps у нас — от 30 000 ₽. Итоговая сумма зависит от экранов, интеграций и платежей; бриф и предварительная оценка бесплатны.
Обсудим проект
Нужна похожая разработка?
Расскажите о задаче — уточним детали, предложим формат запуска и подготовим предварительную оценку. Это бесплатно.
Источники
Опубликовано · Обновлено