Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when: telegram mini app, TWA, telegram web app, TON app, mini app.
Add this skill
npx mdskills install sickn33/telegram-mini-appComprehensive Telegram Mini App guide with actionable code examples and monetization strategies
1---2name: telegram-mini-app3description: "Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when: telegram mini app, TWA, telegram web app, TON app, mini app."4source: vibeship-spawner-skills (Apache 2.0)5---67# Telegram Mini App89**Role**: Telegram Mini App Architect1011You build apps where 800M+ Telegram users already are. You understand12the Mini App ecosystem is exploding - games, DeFi, utilities, social13apps. You know TON blockchain and how to monetize with crypto. You14design for the Telegram UX paradigm, not traditional web.1516## Capabilities1718- Telegram Web App API19- Mini App architecture20- TON Connect integration21- In-app payments22- User authentication via Telegram23- Mini App UX patterns24- Viral Mini App mechanics25- TON blockchain integration2627## Patterns2829### Mini App Setup3031Getting started with Telegram Mini Apps3233**When to use**: When starting a new Mini App3435```javascript36## Mini App Setup3738### Basic Structure39```html40<!DOCTYPE html>41<html>42<head>43 <meta name="viewport" content="width=device-width, initial-scale=1.0">44 <script src="https://telegram.org/js/telegram-web-app.js"></script>45</head>46<body>47 <script>48 const tg = window.Telegram.WebApp;49 tg.ready();50 tg.expand();5152 // User data53 const user = tg.initDataUnsafe.user;54 console.log(user.first_name, user.id);55 </script>56</body>57</html>58```5960### React Setup61```jsx62// hooks/useTelegram.js63export function useTelegram() {64 const tg = window.Telegram?.WebApp;6566 return {67 tg,68 user: tg?.initDataUnsafe?.user,69 queryId: tg?.initDataUnsafe?.query_id,70 expand: () => tg?.expand(),71 close: () => tg?.close(),72 ready: () => tg?.ready(),73 };74}7576// App.jsx77function App() {78 const { tg, user, expand, ready } = useTelegram();7980 useEffect(() => {81 ready();82 expand();83 }, []);8485 return <div>Hello, {user?.first_name}</div>;86}87```8889### Bot Integration90```javascript91// Bot sends Mini App92bot.command('app', (ctx) => {93 ctx.reply('Open the app:', {94 reply_markup: {95 inline_keyboard: [[96 { text: '🚀 Open App', web_app: { url: 'https://your-app.com' } }97 ]]98 }99 });100});101```102```103104### TON Connect Integration105106Wallet connection for TON blockchain107108**When to use**: When building Web3 Mini Apps109110```python111## TON Connect Integration112113### Setup114```bash115npm install @tonconnect/ui-react116```117118### React Integration119```jsx120import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';121122// Wrap app123function App() {124 return (125 <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">126 <MainApp />127 </TonConnectUIProvider>128 );129}130131// Use in components132function WalletSection() {133 return (134 <TonConnectButton />135 );136}137```138139### Manifest File140```json141{142 "url": "https://your-app.com",143 "name": "Your Mini App",144 "iconUrl": "https://your-app.com/icon.png"145}146```147148### Send TON Transaction149```jsx150import { useTonConnectUI } from '@tonconnect/ui-react';151152function PaymentButton({ amount, to }) {153 const [tonConnectUI] = useTonConnectUI();154155 const handlePay = async () => {156 const transaction = {157 validUntil: Math.floor(Date.now() / 1000) + 60,158 messages: [{159 address: to,160 amount: (amount * 1e9).toString(), // TON to nanoton161 }]162 };163164 await tonConnectUI.sendTransaction(transaction);165 };166167 return <button onClick={handlePay}>Pay {amount} TON</button>;168}169```170```171172### Mini App Monetization173174Making money from Mini Apps175176**When to use**: When planning Mini App revenue177178```javascript179## Mini App Monetization180181### Revenue Streams182| Model | Example | Potential |183|-------|---------|-----------|184| TON payments | Premium features | High |185| In-app purchases | Virtual goods | High |186| Ads (Telegram Ads) | Display ads | Medium |187| Referral | Share to earn | Medium |188| NFT sales | Digital collectibles | High |189190### Telegram Stars (New!)191```javascript192// In your bot193bot.command('premium', (ctx) => {194 ctx.replyWithInvoice({195 title: 'Premium Access',196 description: 'Unlock all features',197 payload: 'premium',198 provider_token: '', // Empty for Stars199 currency: 'XTR', // Telegram Stars200 prices: [{ label: 'Premium', amount: 100 }], // 100 Stars201 });202});203```204205### Viral Mechanics206```jsx207// Referral system208function ReferralShare() {209 const { tg, user } = useTelegram();210 const referralLink = `https://t.me/your_bot?start=ref_${user.id}`;211212 const share = () => {213 tg.openTelegramLink(214 `https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=Check this out!`215 );216 };217218 return <button onClick={share}>Invite Friends (+10 coins)</button>;219}220```221222### Gamification for Retention223- Daily rewards224- Streak bonuses225- Leaderboards226- Achievement badges227- Referral bonuses228```229230## Anti-Patterns231232### ❌ Ignoring Telegram Theme233234**Why bad**: Feels foreign in Telegram.235Bad user experience.236Jarring transitions.237Users don't trust it.238239**Instead**: Use tg.themeParams.240Match Telegram colors.241Use native-feeling UI.242Test in both light/dark.243244### ❌ Desktop-First Mini App245246**Why bad**: 95% of Telegram is mobile.247Touch targets too small.248Doesn't fit in Telegram UI.249Scrolling issues.250251**Instead**: Mobile-first always.252Test on real phones.253Touch-friendly buttons.254Fit within Telegram frame.255256### ❌ No Loading States257258**Why bad**: Users think it's broken.259Poor perceived performance.260High exit rate.261Confusion.262263**Instead**: Show skeleton UI.264Loading indicators.265Progressive loading.266Optimistic updates.267268## ⚠️ Sharp Edges269270| Issue | Severity | Solution |271|-------|----------|----------|272| Not validating initData from Telegram | high | ## Validating initData |273| TON Connect not working on mobile | high | ## TON Connect Mobile Issues |274| Mini App feels slow and janky | medium | ## Mini App Performance |275| Custom buttons instead of MainButton | medium | ## Using MainButton Properly |276277## Related Skills278279Works well with: `telegram-bot-builder`, `frontend`, `blockchain-defi`, `viral-generator-builder`280
Full transparency — inspect the skill content before installing.