Telegram MiniApp

Overview

Telegram MiniApp (formerly Web Apps) allows you to build interactive web applications that run inside Telegram. SuperTele provides seamless MiniApp integration with automatic authentication and theme synchronization.

Features

Auto Authentication

Users are automatically authenticated when opening the MiniApp, no manual login required.

Theme Sync

MiniApp automatically syncs with Telegram's light/dark theme settings.

Native Experience

Leverage Telegram's native UI components for a seamless user experience.

How It Works

User Opens MiniApp

User opens MiniApp from Bot menu or inline button.

Telegram Injects initData

Telegram client injects initData containing user information and signature.

Server Validates initData

Server validates the signature using Bot Token to ensure data authenticity.

Create or Link User

If the Telegram user doesn't exist, create a new account; otherwise, link to existing account.

Establish Session

Create a session and return to the MiniApp, user is now logged in.

Configuration

Environment Variables

# Required for MiniApp auth validation
TELEGRAM_BOT_TOKEN=your_bot_token

MiniApp Provider

The template includes TelegramMiniAppProvider that handles authentication automatically:

// src/components/providers/telegram-miniapp-provider.tsx
<TelegramMiniAppProvider>
  {children}
</TelegramMiniAppProvider>

Detecting MiniApp Environment

Use the useTelegramMiniApp hook to detect if the app is running inside Telegram:

import { useTelegramMiniApp } from '@/hooks/use-telegram-miniapp';

function MyComponent() {
  const { isMiniApp, isLoading } = useTelegramMiniApp();

  if (isMiniApp) {
    // Running inside Telegram MiniApp
    return <MiniAppUI />;
  }

  // Running in regular browser
  return <WebUI />;
}

MiniApp-Specific Features

Hide Elements in MiniApp

Some UI elements should be hidden in MiniApp context:

const { isMiniApp } = useTelegramMiniApp();

return (
  <div>
    {!isMiniApp && <Header />}
    <MainContent />
    {!isMiniApp && <Footer />}
  </div>
);

Telegram UI Components

Use Telegram's native components for better integration:

MainButton - Bottom action button
BackButton - Navigation back button
HapticFeedback - Vibration feedback
CloudStorage - Persistent storage

File Structure

src/
├── components/providers/
│   └── telegram-miniapp-provider.tsx  # Auth provider
├── hooks/
│   └── use-telegram-miniapp.ts        # MiniApp detection hook
└── app/api/telegram/miniapp/
    └── auth/route.ts                  # Auth API endpoint

Learn More