gramdocs.tech
Документация

Telegram Mini Apps: что это и как работают

Поймёшь, что такое Mini App в Telegram, как оно запускается из бота и чем отличается от обычного сайта.

Telegram Mini Apps

Telegram Mini App — это веб-приложение (HTML/CSS/JS), которое открывается внутри клиента Telegram: в чате с ботом, из меню, по прямой ссылке или из inline-кнопки. Для пользователя это выглядит как экран внутри Telegram; для тебя — обычный фронтенд плюс доступ к window.Telegram.WebApp.

Мини-приложение не живёт «внутри» Telegram как нативный код: Telegram открывает твой URL в WebView и инжектит JS API. Бэкенд — твой; бот — точка входа и канал сообщений.

Как запускается Mini App

Типичный путь:

text
Пользователь → бот / ссылка t.me/...
           → Telegram открывает твой HTTPS URL в WebView
           → подключается telegram-web-app.js
           → доступен window.Telegram.WebApp
           → initData с данными пользователя (подписаны Telegram)

Минимальный HTML-каркас:

html
<!DOCTYPE html>
<html lang="ru">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
    />
    <!-- Telegram WebApp script, Bot API / docs: telegram.org/js/telegram-web-app.js -->
    <script src="https://telegram.org/js/telegram-web-app.js"></script>
    <title>My Mini App</title>
  </head>
  <body>
    <h1 id="hello">Loading…</h1>
    <script>
      const tg = window.Telegram.WebApp;
      tg.ready();
      tg.expand();

      const user = tg.initDataUnsafe.user;
      document.getElementById("hello").textContent = user
        ? `Привет, ${user.first_name}`
        : "Открой из Telegram";
    </script>
  </body>
</html>

initDataUnsafe удобен для UI, но не для авторизации на сервере — подпись проверяют на бэкенде (см. следующую статью про initData).

Как это работает

  • WebView — Telegram рендерит твою страницу; домен и хостинг — твои.
  • telegram-web-app.js — даёт Telegram.WebApp: тема, кнопки, initData, CloudStorage и т.д.
  • Бот — регистрирует URL (Menu Button, Keyboard web_app, ссылка) и может принимать данные через Bot API.
  • HTTPS — обязателен для продакшн-URL; без него клиент не откроет Mini App штатно.

Частые ошибки

Считаешь Mini App «частью бота» без отдельного фронта → бот только запускает URL. UI и логика — твой веб-стек.

Доверяешь initDataUnsafe.user.id на сервере → данные можно подделать в DevTools. Валидируй initData HMAC на бэкенде.

Открываешь file:// или http:// в проде → нужен публичный HTTPS. Для локальной разработки — туннель (ngrok, cloudflared) с HTTPS.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация