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

Telegram WebApp API: инициализация приложения

Подключишь telegram-web-app.js, вызовешь ready/expand и прочитаешь базовые поля WebApp.

Инициализация WebApp API

После загрузки telegram-web-app.js в странице появляется window.Telegram.WebApp. Первые вызовы при старте: сообщить клиенту, что UI готов (ready), и при необходимости развернуть окно на всю высоту (expand).

Без ready() Telegram может дольше показывать плейсхолдер загрузки. Без expand() приложение часто открывается компактной высотой.

Подключаем API и стартуем

typescript
// Telegram WebApp JS (официальный скрипт: telegram.org/js/telegram-web-app.js)
// Типы: npm i -D @twa-dev/types  (или свой declare)

declare global {
  interface Window {
    Telegram: {
      WebApp: {
        ready: () => void;
        expand: () => void;
        close: () => void;
        isExpanded: boolean;
        viewportHeight: number;
        viewportStableHeight: number;
        platform: string;
        version: string;
        colorScheme: "light" | "dark";
        initData: string;
        initDataUnsafe: {
          user?: {
            id: number;
            first_name: string;
            last_name?: string;
            username?: string;
            language_code?: string;
          };
          auth_date?: number;
          hash?: string;
          start_param?: string;
        };
      };
    };
  }
}

export function bootstrapMiniApp(): void {
  const tg = window.Telegram?.WebApp;
  if (!tg) {
    throw new Error("Telegram.WebApp недоступен — открой страницу внутри Telegram");
  }

  // Сообщаем клиенту: можно скрыть loading placeholder
  tg.ready();

  // Разворачиваем на максимальную доступную высоту
  tg.expand();

  console.log({
    platform: tg.platform, // ios | android | tdesktop | web ...
    version: tg.version,
    colorScheme: tg.colorScheme,
    isExpanded: tg.isExpanded,
    viewportHeight: tg.viewportHeight,
    startParam: tg.initDataUnsafe.start_param,
  });
}

bootstrapMiniApp();

В HTML скрипт Telegram должен идти до твоего бандла:

html
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script type="module" src="/app.js"></script>

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

  • ready() — Telegram прячет loading placeholder и показывает страницу.
  • expand() — запрос на максимальную высоту WebView; факт смотри в isExpanded.
  • initData — сырая query-string с подписью; её шлёшь на бэкенд.
  • initDataUnsafe — уже распарсенный объект для UI (без проверки подписи).
  • platform / version — клиент и версия WebApp API; полезно для feature-detect.

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

Скрипт своего приложения раньше telegram-web-app.js → window.Telegram ещё нет. Порядок: сначала официальный скрипт, потом твой код.

Тестируешь только в обычном браузере → API пустой или отсутствует. Для проверки нужен Telegram-клиент + HTTPS URL (или туннель).

Игнорируешь viewportStableHeight → при открытой клавиатуре viewportHeight прыгает; для layout часто берут stable-значение.

Что дальше

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