Принцип работы Telegram Mini Apps
Telegram Mini App представляет собой одностраничное веб-приложение, которое открывается внутри встроенного контейнера WebView в мобильных, десктопных и веб-клиентах мессенджера. Приложение размещается на внешнем сервере разработчика и передаётся по протоколу HTTPS, что позволяет использовать привычные веб-технологии и библиотеки интерфейса.
Связующим звеном между веб-страницей и приложением Telegram выступает скрипт Telegram WebApp. После загрузки мост предоставляет доступ к параметрам темы, управлению нативными кнопками мессенджера и безопасным данным пользователя без необходимости повторного ввода логина и пароля.
Когда Mini App эффективнее обычного чат-бота
Обычные чат-боты на основе встроенных клавиатур и текстовых сообщений подходят для простых линейных сценариев: подтверждений, уведомлений и коротких опросников. Однако попытка упаковать сложный каталог или ветвистый опрос в ленту сообщений быстро перегружает чат и усложняет навигацию.
Переход к веб-интерфейсу оправдан в сценариях, требующих высокой плотности информации и нелинейных действий пользователя: Трудоёмкость обоих вариантов разобрана в статье стоимость разработки Telegram-бота.
- Каталоги товаров и услуг с фильтрацией по нескольким параметрам, сортировкой и карточками.
- Оформление заказа с корзиной, редактированием позиций и расчётом итоговой стоимости.
- Интерактивные календари, выбор слотов для записи или бронирование мест на схеме зала.
- Личные кабинеты с просмотром истории операций, баланса и детальных статусов.
- Сложные многостраничные анкеты, где пользователю важно возвращаться назад и редактировать введённые поля.
Взаимодействие с клиентом через WebApp API
Интерфейсный мост Telegram WebApp позволяет веб-приложению выглядеть частью нативного клиента мессенджера. Разработчикам не нужно рисовать собственные нижние панели подтверждения: приложение может напрямую управлять нативными элементами Main Button, Secondary Button и Back Button.
Кроме управления навигацией, API передаёт параметры темы оформления. Отслеживание изменений темы позволяет стилям приложения синхронно переключаться между светлым и тёмным оформлением вслед за настройками самого Telegram.
- Управление нативными кнопками Main Button и Back Button для привычной мобильной навигации.
- Синхронизация цветовой палитры с параметрами активной темы оформления мессенджера.
- Вызов тактильного отклика через модуль тактильной обратной связи при подтверждении действий.
- Контроль высоты области просмотра и раскрытие приложения на полный экран.
Валидация подписи initData и безопасность бэкенда
При запуске приложения Telegram передаёт в параметрах строку initData, содержащую идентификатор пользователя, параметры сессии, время генерации и криптографическую подпись hash. Доверять данным, переданным на клиенте, нельзя: сервер обязан проверить валидность подписи перед созданием пользовательской сессии или сохранением данных.
Алгоритм проверки строго регламентирован. Сервер разбирает строку параметров, исключает поле hash и сортирует оставшиеся пары ключ-значение в алфавитном порядке. Секретный ключ вычисляется как HMAC-SHA256 от токена бота с использованием константной строки WebAppData. Затем рассчитывается HMAC-SHA256 от отсортированной строки данных с полученным ключом. Если итоговый хэш совпадает с переданным в параметрах, а время создания подписи укладывается в допустимый интервал, данные считаются подлинными.
Приём платежей за цифровые и физические товары
Архитектура расчётов в Mini Apps разделяется в зависимости от типа реализуемого продукта. При продаже цифровых товаров и виртуальных услуг внутри экосистемы Telegram используется внутренняя платёжная единица Telegram Stars. Сервер бота формирует ссылку на инвойс, а веб-приложение инициирует нативное окно оплаты через метод openInvoice.
Для физических товаров и внешних услуг применяются подключённые к боту платёжные шлюзы провайдеров эквайринга. После подтверждения списания средств мессенджер отправляет уведомление на вебхук бота, и бэкенд фиксирует оплату заказа в своей базе данных. Работу со счетами и проверкой оплаты на стороне бота описывает статья оплата в Telegram-боте.
Ограничения платформы и проектирование UX
Разработка для WebView накладывает ряд ограничений, отличающихся от стандартной веб-разработки для браузера. В мобильных клиентах присутствует нативный жест смахивания для закрытия шторки, который может случайно сработать при прокрутке длинного списка. В интерфейсе необходимо настраивать обработку вертикальных свайпов и учитывать безопасные отступы вокруг вырезов экрана.
Критическое значение имеет скорость первой отрисовки. Поскольку приложение загружается во встроенном контейнере, размер пакета скриптов и стилей должен быть минимальным. Разделение кода, сжатие статических ресурсов и предварительная загрузка данных помогают избежать задержек при открытии приложения.