Telegram Web Apps (TWA): Как запустить полноценный SaaS внутри Telegram

Telegram давно перешагнул рамки классического мессенджера для обмена сообщениями, превратившись в полноценную кроссплатформенную среду выполнения приложений. С появлением технологии Telegram Web Apps (TWA), также известной как Telegram Mini Apps, разработчики могут запускать интерактивные SPA-приложения прямо внутри интерфейса мессенджера.

Это дает стартапам и бизнесу мгновенный бесшовный доступ к аудитории более 900 миллионов активных пользователей. Размещая свой B2B SaaS, личный кабинет CRM или бизнес-инструмент в боте Telegram, вы устраняете классические барьеры воронки: необходимость скачивать приложения из сторов, регистрироваться и авторизовываться на сторонних сайтах.

В этом техническом руководстве мы разберем архитектуру TWA, напишем безопасный бэкенд-валидатор на Node.js/TypeScript и настроим синхронизацию стилей на фронтенде.

Архитектура экосистемы Telegram Mini Apps

В отличие от стандартных веб-приложений, TWA имеет двухстороннюю связь с клиентом. Фронтенд работает в изолированном компоненте WebView, контролируемом клиентом Telegram, в то время как бэкенд взаимодействует как с API Telegram Bot, так и с базой данных приложения.

+-----------------------------------------------------------+
|                     Клиент Telegram                       |
|  +-----------------------------------------------------+  |
|  |                 Mini App (WebView UI)               |  |
|  |     (Использует window.Telegram.WebApp SDK)         |  |
|  +--------------------------+--------------------------+  |
+-----------------------------|-----------------------------+
       | (initData параметры) | (Защищенный HTTPS-запрос)
       v                      v
+--------------+       +------------------------------------+
| Telegram API |       |            Ваш Бэкенд              |
|  (Вебхуки)   |       | (Проверяет подпись через HMAC-256) |
+------+-------+       +-----------------+------------------+
       |                                 |
       +----------------> [Синхр. БД] <---+

1. Безопасность: Валидация строки initData

Когда пользователь открывает Mini App, Telegram передает на фронтенд строку параметров initData (содержащую данные профиля пользователя, тему оформления, контекст запуска) и защитную подпись hash.

Чтобы злоумышленники не могли подделать идентификатор пользователя (User ID) или эмулировать оплату тарифа, вы обязаны валидировать этот хэш на вашем бэкенде с помощью токена вашего Telegram-бота.

Вот реализация валидации на TypeScript/Node.js:

import crypto from 'crypto';

interface TelegramUserData {
  id: number;
  first_name: string;
  last_name?: string;
  username?: string;
  language_code?: string;
  is_premium?: boolean;
}

interface ValidationResult {
  isValid: boolean;
  user?: TelegramUserData;
}

export function verifyTelegramInitData(rawQueryString: string, botToken: string): ValidationResult {
  const urlParams = new URLSearchParams(rawQueryString);
  const hash = urlParams.get('hash');
  
  if (!hash) {
    return { isValid: false };
  }

  // 1. Сортируем все переданные ключи в алфавитном порядке, кроме самого hash
  const keys = Array.from(urlParams.keys()).filter(key => key !== 'hash').sort();
  
  // 2. Восстанавливаем проверочную строку данных
  const dataCheckString = keys
    .map(key => `${key}=${urlParams.get(key)}`)
    .join('\n');

  // 3. Создаем секретный ключ
  // Мы используем константную строку "WebAppData" для шифрования токена бота
  const secretKey = crypto
    .createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest();

  // 4. Вычисляем хэш-сигнатуру от проверочной строки
  const computedHash = crypto
    .createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');

  // 5. Безопасно сравниваем вычисленный хэш с тем, который прислал клиент
  const isValid = computedHash === hash;

  if (!isValid) {
    return { isValid: false };
  }

  // Десериализуем объект пользователя, если валидация прошла успешно
  try {
    const userRaw = urlParams.get('user');
    const user: TelegramUserData = userRaw ? JSON.parse(userRaw) : undefined;
    return { isValid: true, user };
  } catch (error) {
    return { isValid: true };
  }
}

2. Интеграция во фронтенд и адаптация темы оформления

Для создания премиального интерфейса (UI/UX) приложение должно подстраиваться под цветовую гамму клиента Telegram (темная/светлая тема). Доступ к этим параметрам осуществляется через библиотеку JS-моста.

Шаг 1: Подключение скрипта в Nuxt 3 / HTML

Добавьте скрипт в секцию head в Nuxt с помощью composable useHead:

// app.vue или layout страницы
useHead({
  script: [
    { src: 'https://telegram.org/js/telegram-web-app.js', defer: true }
  ]
})

Шаг 2: Использование JS-моста в Vue-компонентах

Создадим реактивный composable для считывания настроек Telegram:

// composables/useTelegram.ts
import { ref, onMounted } from 'vue';

export function useTelegram() {
  const isReady = ref(false);
  const user = ref<any>(null);

  onMounted(() => {
    const tg = (window as any).Telegram?.WebApp;
    if (tg) {
      tg.ready();
      tg.expand(); // Разворачиваем окно на максимальную высоту
      
      user.value = tg.initDataUnsafe?.user;
      isReady.value = true;

      // Передаем цвета темы Telegram в переменные CSS (Custom Properties)
      const root = document.documentElement;
      root.style.setProperty('--color-tg-bg', tg.themeParams.bg_color);
      root.style.setProperty('--color-tg-text', tg.themeParams.text_color);
      root.style.setProperty('--color-tg-button', tg.themeParams.button_color);
      root.style.setProperty('--color-tg-button-text', tg.themeParams.button_text_color);
    }
  });

  return { isReady, user };
}

3. Прием платежей через Telegram Stars

При продаже цифровых товаров (подписки на SaaS, баланс лимитов ИИ, инфопродукты) правила Apple/Google обязывают использовать внутреннюю валюту мессенджера — Telegram Stars (XTR).

Алгоритм покупки цифрового товара:

1. Создание счета: TWA запрашивает бэкенд сгенерировать счет на оплату.
2. Отправка инвойса: Бэкенд делает запрос к Bot API sendInvoice с валютой XTR.
3. Оплата в клиенте: Telegram открывает нативный экран оплаты, где пользователь списывает «Звезды».
4. Синхронизация: Приходит вебхук successful_payment на бэкенд бота, после чего лимиты зачисляются в вашей базе данных.

В моей платформе конструктора ботов TeleGo.io мы предоставляем именно такие встроенные платежные сценарии, позволяя пользователям создавать свои TWA и сразу принимать Stars. Кроме того, мы поддерживаем гибридные хелпдески поддержки, о настройке которых вы можете узнать в статье Как создать ИИ-бота поддержки с RAG.

Для физических товаров и консультаций можно использовать классический биллинг. Читайте мое руководство Монетизация SaaS и интеграция Stripe для ознакомления со скриптами Express/TypeScript.

Источники и документация

• Telegram Mini Apps — официальная документация WebApp SDK и initData
• Bot Payments API — счета, Telegram Stars и вебхуки оплат

Сочетание современных веб-фронтендов с API Telegram WebApp позволяет создавать удобные B2B-продукты внутри популярного мессенджера, минуя сложные регистрационные формы.

Если вы планируете разработку Telegram Mini App с платежами Stars/Stripe и динамической темой оформления, ознакомьтесь с моей услугой Создание Telegram-ботов или запишитесь на Консультацию, чтобы разработать архитектуру.