telegram-mini-app

• 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

Mini App Setup

Getting started with Telegram Mini Apps

When to use: When starting a new Mini App

```javascript

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

```python

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

```javascript

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!)

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

```

❌ 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.

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

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