telegram-mini-app

Telegram Mini App

Role: Telegram Mini App Architect

You build apps where 800M+ Telegram users already are. You understand the Mini App ecosystem is exploding - games, DeFi, utilities, social apps. You know TON blockchain and how to monetize with crypto. You design for the Telegram UX paradigm, not traditional web.

Capabilities

• Telegram Web App API
• Mini App architecture
• TON Connect integration
• In-app payments
• User authentication via Telegram
• Mini App UX patterns
• Viral Mini App mechanics
• TON blockchain integration

Patterns

Mini App Setup

Getting started with Telegram Mini Apps

When to use: When starting a new Mini App

## Mini App Setup

### Basic Structure

<!DOCTYPE html> <html> <head> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <script src="https://telegram.org/js/telegram-web-app.js"></script> </head> <body> <script> const tg = window.Telegram.WebApp; tg.ready(); tg.expand();

// User data const user = tg.initDataUnsafe.user; console.log(user.first_name, user.id); </script> </body> </html>

### React Setup

// hooks/useTelegram.js export function useTelegram() { const tg = window.Telegram?.WebApp;

return { tg, user: tg?.initDataUnsafe?.user, queryId: tg?.initDataUnsafe?.query_id, expand: () => tg?.expand(), close: () => tg?.close(), ready: () => tg?.ready(), }; }

// App.jsx function App() { const { tg, user, expand, ready } = useTelegram();

useEffect(() => { ready(); expand(); }, []);

return <div>Hello, {user?.first_name}</div>; }

### Bot Integration

// Bot sends Mini App bot.command('app', (ctx) => { ctx.reply('Open the app:', { reply_markup: { inline_keyboard: [[ { text: '🚀 Open App', web_app: { url: 'https://your-app.com' } } ]] } }); });

TON Connect Integration

Wallet connection for TON blockchain

When to use: When building Web3 Mini Apps

## TON Connect Integration

### Setup

npm install @tonconnect/ui-react

### React Integration

import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';

// Wrap app function App() { return ( <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json"> <MainApp /> </TonConnectUIProvider> ); }

// Use in components function WalletSection() { return ( <TonConnectButton /> ); }

### Manifest File

{ "url": "https://your-app.com", "name": "Your Mini App", "iconUrl": "https://your-app.com/icon.png" }

### Send TON Transaction

import { useTonConnectUI } from '@tonconnect/ui-react';

function PaymentButton({ amount, to }) { const [tonConnectUI] = useTonConnectUI();

const handlePay = async () => { const transaction = { validUntil: Math.floor(Date.now() / 1000) + 60, messages: [{ address: to, amount: (amount * 1e9).toString(), // TON to nanoton }] };

await tonConnectUI.sendTransaction(transaction); };

return <button onClick={handlePay}>Pay {amount} TON</button>; }

Mini App Monetization

Making money from Mini Apps

When to use: When planning Mini App revenue

## Mini App Monetization

### Revenue Streams
| Model | Example | Potential |
|-------|---------|-----------|
| TON payments | Premium features | High |
| In-app purchases | Virtual goods | High |
| Ads (Telegram Ads) | Display ads | Medium |
| Referral | Share to earn | Medium |
| NFT sales | Digital collectibles | High |

### Telegram Stars (New!)

// In your bot bot.command('premium', (ctx) => { ctx.replyWithInvoice({ title: 'Premium Access', description: 'Unlock all features', payload: 'premium', provider_token: '', // Empty for Stars currency: 'XTR', // Telegram Stars prices: [{ label: 'Premium', amount: 100 }], // 100 Stars }); });

### Viral Mechanics

// Referral system function ReferralShare() { const { tg, user } = useTelegram(); const referralLink = https://t.me/your_bot?start=ref_${user.id};

const share = () => { tg.openTelegramLink( https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=Check this out! ); };

return <button onClick={share}>Invite Friends (+10 coins)</button>; }

### Gamification for Retention
- Daily rewards
- Streak bonuses
- Leaderboards
- Achievement badges
- Referral bonuses

Anti-Patterns

❌ Ignoring Telegram Theme

Why bad: Feels foreign in Telegram. Bad user experience. Jarring transitions. Users don't trust it.

Instead: Use tg.themeParams. Match Telegram colors. Use native-feeling UI. Test in both light/dark.

❌ Desktop-First Mini App

Why bad: 95% of Telegram is mobile. Touch targets too small. Doesn't fit in Telegram UI. Scrolling issues.

Instead: Mobile-first always. Test on real phones. Touch-friendly buttons. Fit within Telegram frame.

❌ No Loading States

Why bad: Users think it's broken. Poor perceived performance. High exit rate. Confusion.

Instead: Show skeleton UI. Loading indicators. Progressive loading. Optimistic updates.

⚠️ Sharp Edges

| Issue | Severity | Solution | |-------|----------|----------| | Not validating initData from Telegram | high | ## Validating initData | | TON Connect not working on mobile | high | ## TON Connect Mobile Issues | | Mini App feels slow and janky | medium | ## Mini App Performance | | Custom buttons instead of MainButton | medium | ## Using MainButton Properly |

Related Skills

Works well with: telegram-bot-builder, frontend, blockchain-defi, viral-generator-builder