Кнопка «Открыть» в чате с ботом, а за ней полноценное приложение: каталог, корзина, профиль. Кажется, что для этого нужен отдельный фреймворк 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, сверить время и держать токен при себе. Сделайте это с первого дня, и приложение можно спокойно показывать людям.