Содержание статьи
Коротко о главном
- Мини-приложение — веб-страница по HTTPS, подключённая к боту через кнопку меню или как главное мини-приложение в BotFather.
- Скрипт telegram-web-app.js подключают в head раньше всех остальных скриптов.
- Данным initDataUnsafe на странице доверять нельзя. Сервер проверяет initData подписью от токена бота и сверяет время auth_date.
- Токен бота живёт только на сервере, в код страницы его не кладут никогда.
- Перед запуском проверьте приложение на iOS, Android и компьютере: у каждой платформы есть свой режим отладки.
Кнопка «Открыть» в чате с ботом, а за ней полноценное приложение: каталог, корзина, профиль. Кажется, что для этого нужен отдельный фреймворк Telegram. На деле внутри обычная веб-страница, которую Telegram открывает в своём окне и передаёт ей данные о пользователе.
Собрать такую страницу может любой, кто делал сайты. Сложность в другом: страница открывается и в обычном браузере, где никакого Telegram нет. Поэтому решает не красота интерфейса, а то, проверяет ли сервер, что пользователь настоящий.
- 7 способов
- Столько способов запуска мини-приложений перечисляет документация Telegram.
- 4 платформы
- Где стоит проверить приложение перед запуском: iOS, Android, Telegram Desktop и Telegram для macOS.
Подготовка
Что понадобится
- Бот в BotFather — к нему привязывается мини-приложение. Как его создать, разобрано в статье «Как создать бота в Telegram: BotFather, первый код на Python и одно правило про токен».
- Страница по HTTPS. Telegram открывает мини-приложение по адресу с TLS. Без него работает только тестовая среда.
- Сервер, который хранит токен бота и проверяет данные запуска. Это может быть тот же сервер, где работает бот.
BotFather
Шаг 1. Подключите страницу к боту
Способов открыть мини-приложение семь: главная кнопка в профиле бота, кнопка меню, кнопка клавиатуры, кнопка в сообщении, встроенный режим, прямая ссылка и меню вложений. Для начала хватит двух.
- Кнопка меню. В BotFather: /setmenubutton или Bot Settings → Menu Button, затем адрес страницы. Кнопка появится рядом с полем ввода в чате с ботом.
- Главное мини-приложение. В BotFather: /mybots → ваш бот → Bot Settings → Configure Mini App → Enable Mini App. В профиле бота появится кнопка запуска, а приложение откроется по ссылке t.me/имя_бота?startapp.
Параметр после startapp попадает в приложение в поле start_param — так можно открыть нужный раздел или передать код приглашения.
Код клиента
Шаг 2. Страница
Скрипт Telegram подключают в head раньше любых других скриптов. Данные о пользователе в initDataUnsafe годятся только для показа, а на сервер отправляют сырую строку initData.
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
<h1 id="hello">Загрузка…</h1>
<script>
const tg = window.Telegram.WebApp;
tg.ready();
// Только для показа: этим данным нельзя доверять
const user = tg.initDataUnsafe.user;
document.getElementById("hello").textContent =
user ? "Привет, " + user.first_name : "Откройте страницу из Telegram";
// На сервер отправляем сырую строку для проверки
fetch("/api/session", { method: "POST", body: tg.initData });
</script>
</body>
</html>Код сервера
Шаг 3. Проверка на сервере
Сервер проверяет, что строка initData действительно пришла от Telegram. Алгоритм из документации: все поля, кроме hash, сортируются по имени и склеиваются через перевод строки в виде ключ=значение. Секретный ключ — HMAC-SHA-256 токена бота с ключом WebAppData. Подпись этой строки секретным ключом должна совпасть с полем hash. Ещё стоит проверить auth_date, чтобы не принимать старые данные.
"""Проверка initData мини-приложения. Python 3.10+, только стандартная библиотека."""
import hashlib
import hmac
import time
from urllib.parse import parse_qsl
def check_init_data(init_data, bot_token, max_age_seconds=3600):
fields = dict(parse_qsl(init_data, keep_blank_values=True))
received_hash = fields.pop("hash", "")
if not received_hash:
return None
data_check_string = "\n".join(
f"{key}={value}" for key, value in sorted(fields.items())
)
secret_key = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
expected = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, received_hash):
return None
if time.time() - int(fields.get("auth_date", "0")) > max_age_seconds:
return None
return fields # поле user — JSON-строка с данными пользователяЕсли функция вернула None, запрос отклоняют. Если вернула поля, данным можно доверять: создавайте сессию и работайте с пользователем по его ID.
Важно
Без проверки любой может представиться кем угодно
Страницу мини-приложения можно открыть в обычном браузере и подставить в initDataUnsafe любое имя и любой ID. Если сервер верит этим данным без проверки подписи, злоумышленник войдёт от имени другого пользователя, получит его покупки или бонусы. Проверяйте initData на сервере при каждом входе и никогда не кладите токен бота в код страницы.
Если данные нужно передать стороннему сервису без токена бота, в initData есть поле signature: его проверяют открытым ключом Telegram по алгоритму Ed25519. Подробности — в документации Telegram.

Тестирование
Шаг 4. Отладка на трёх платформах
- iOS: десять раз нажмите на значок настроек в Telegram и включите Allow Web View Inspection. Подключите телефон к Mac и откройте Safari → Develop → ваше устройство.
- Android: включите отладку по USB, в настройках Telegram внизу дважды нажмите и удерживайте номер версии, выберите Enable WebView Debug. Откройте chrome://inspect/#devices в Chrome на компьютере.
- Telegram Desktop на Windows и Linux: в бета-версии включите Settings → Advanced → Experimental settings → Enable webview inspection, затем правый клик внутри приложения → Inspect.
- Telegram для macOS: в бета-версии пять раз быстро нажмите на значок настроек и включите Debug Mini Apps.
Для экспериментов есть тестовая среда Telegram: там свой аккаунт, свой BotFather и разрешены ссылки без HTTPS.
Чек-лист
Перед запуском
О правилах оплаты подробно — в статье «Как принимать оплату в Telegram-боте: Stars, карта или GRAM».
Вопросы
Можно ли сделать мини-приложение без своего сервера?
Статическую страницу можно разместить где угодно. Но если приложение что-то хранит, продаёт или выдаёт бонусы, без сервера с проверкой initData оно беззащитно: доверять данным на самой странице нельзя.
Какие данные о пользователе получает мини-приложение?
ID, имя, ник, язык, отметку Premium и, если позволяют настройки, фото профиля. Номер телефона и переписку оно не получает без отдельного разрешения. Подробнее — в статье «Разрешения мини-приложений Telegram: что вы отдаёте, когда жмёте „Разрешить“».
Как попасть в каталог мини-приложений Telegram?
Telegram может показать в Mini App Store успешных ботов с главным мини-приложением, которые принимают оплату в Stars. Шансы повышают качественные видео и скриншоты в профиле бота.
Mini App — это сайт, которому Telegram дал окно, кнопку запуска и данные о пользователе. Собрать интерфейс несложно, и документация Telegram подробно описывает каждый шаг.
Главная работа — на сервере: проверить подпись initData, сверить время и держать токен при себе. Сделайте это с первого дня, и приложение можно спокойно показывать людям.


