Что такое Telegram Mini App и как оно работает
Основы3 минРедакция Innovialabs
Коротко
Telegram Mini App — это обычный сайт на HTML, CSS и JavaScript, который открывается внутри Telegram по кнопке или ссылке бота и получает доступ к данным пользователя, теме оформления, кнопкам и платежам Telegram без отдельной регистрации.
Коротко: что такое Mini App
Telegram Mini App (раньше — Web App) — это веб-приложение, которое Telegram открывает в своём встроенном окне поверх чата. Технически это сайт: вы пишете его на любом фронтенд-стеке, размещаете по HTTPS-адресу и привязываете к боту.
Отличие от обычного сайта в том, что Mini App:
- открывается в один тап, без перехода в браузер;
- сразу знает, кто его открыл, — без логина и пароля;
- подстраивается под тему Telegram и использует его кнопки, вибрацию, платежи.
Mini App всегда связан с ботом: бот — это «точка входа» и канал для сообщений, приложение — полноценный интерфейс.
Как это работает под капотом
- Пользователь нажимает кнопку или ссылку.
- Telegram открывает ваш URL во встроенном WebView.
- На странице подключается официальный скрипт
telegram-web-app.js, и появляется объектwindow.Telegram.WebApp. - Telegram передаёт в приложение initData — данные о пользователе и подпись.
- Ваш сервер проверяет подпись с помощью токена бота и доверяет данным только после проверки.
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
const tg = window.Telegram.WebApp;
tg.ready();
// tg.initData отправляем на сервер для проверки подписи
</script>
Важно: initDataUnsafe на клиенте удобно для отображения имени, но для авторизации всегда используйте проверку initData на сервере.
Откуда запускается Mini App
| Точка входа | Как выглядит | Когда удобна |
|---|---|---|
| Кнопка меню | Кнопка слева от поля ввода в чате с ботом | Основной вход: магазин, личный кабинет |
| Inline-кнопка | Кнопка под сообщением бота | Контекстное действие: «Оформить заказ», «Выбрать время» |
| Кнопка клавиатуры | Кнопка вместо обычной клавиатуры | Когда нужно вернуть данные обратно в чат |
| Прямая ссылка | Ссылка вида t.me/имя_бота/имя_приложения | Реклама, QR-код, пост в канале |
| Кнопка в профиле бота | «Открыть приложение» в профиле | Когда у бота настроено основное приложение |
Прямая ссылка может передавать параметр startapp, чтобы открыть нужный раздел или учесть источник перехода.
Какие нативные функции доступны
- Данные пользователя: id, имя, язык, username — без формы регистрации.
- Тема: цвета текущей темы Telegram, чтобы приложение выглядело «родным» в светлом и тёмном режиме.
- Системные кнопки: главная кнопка внизу экрана, кнопка «Назад», кнопка настроек.
- Тактильный отклик: вибрация при нажатиях и ошибках.
- Облачное хранилище: небольшие данные пользователя, которые хранит Telegram.
- Платежи: открытие счёта прямо из приложения, в том числе в Telegram Stars.
- Запросы к пользователю: поделиться контактом, разрешить боту писать, отсканировать QR-код.
- Полноэкранный режим, геолокация, биометрия — в актуальных версиях клиентов.
Набор функций зависит от версии Telegram у пользователя, поэтому перед вызовом проверяйте поддержку через isVersionAtLeast.
Когда Mini App лучше бота с кнопками
- Много товаров, фильтров, фотографий.
- Нужны формы с несколькими полями и валидацией.
- Есть личный кабинет, история заказов, корзина.
- Важен фирменный дизайн, а не только текст.
Если сценарий — три вопроса и ответ, обычного бота достаточно: его быстрее сделать и проще поддерживать.
Частые ошибки
- Доверять данным пользователя без проверки подписи на сервере.
- Делать интерфейс под десктоп: большинство открывает Mini App на телефоне.
- Игнорировать тему Telegram — белый экран в тёмном режиме выглядит чужеродно.
- Забывать про кнопку «Назад» и навигацию внутри приложения.