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

html

### React Setup

jsx
// 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

;
}

### Bot Integration

javascript
// 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

bash
npm install @tonconnect/ui-react

### React Integration

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

// Wrap app
function App() {
return (



);
}

// Use in components
function WalletSection() {
return (

);
}

### Manifest File

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

### Send TON Transaction

jsx
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 Pay {amount} TON;
}

Mini App Monetization

Making money from Mini Apps

When to use: When planning Mini App revenue

## Mini App Monetization
Revenue Streams

<div class="overflow-x-auto my-6"><table class="min-w-full divide-y divide-border border border-border"><thead><tr><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Model</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Example</th><th class="px-4 py-2 text-left text-sm font-semibold text-foreground bg-muted/50">Potential</th></tr></thead><tbody class="divide-y divide-border"><tr><td class="px-4 py-2 text-sm text-foreground">TON payments</td><td class="px-4 py-2 text-sm text-foreground">Premium features</td><td class="px-4 py-2 text-sm text-foreground">High</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">In-app purchases</td><td class="px-4 py-2 text-sm text-foreground">Virtual goods</td><td class="px-4 py-2 text-sm text-foreground">High</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Ads (Telegram Ads)</td><td class="px-4 py-2 text-sm text-foreground">Display ads</td><td class="px-4 py-2 text-sm text-foreground">Medium</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">Referral</td><td class="px-4 py-2 text-sm text-foreground">Share to earn</td><td class="px-4 py-2 text-sm text-foreground">Medium</td></tr><tr><td class="px-4 py-2 text-sm text-foreground">NFT sales</td><td class="px-4 py-2 text-sm text-foreground">Digital collectibles</td><td class="px-4 py-2 text-sm text-foreground">High</td></tr></tbody></table></div>
Telegram Stars (New!)

javascript
// 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

jsx
// 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 Invite Friends (+10 coins);
}

### 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

Related Skills

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