telegram-mini-app
构建可在 Telegram 内运行的轻量级 Web 应用,支持无缝集成 TON 区块链钱包与原生用户认证,实现支付、社交裂变及游戏化功能,适用于开发高传播性、多端适配且具备 Web3 货币化能力的沉浸式应用体验。
区块链效率工具
| name | telegram-mini-app |
| description | 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. |
| source | vibeship-spawner-skills (Apache 2.0) |
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
▼javascript复制代码## Mini App Setup ### Basic Structure ```html <!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
▼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 <div>Hello, {user?.first_name}</div>; }
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' } } ]] } }); });
▼text复制代码### TON Connect Integration Wallet connection for TON blockchain **When to use**: When building Web3 Mini Apps ```python ## 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 ( <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json"> <MainApp /> </TonConnectUIProvider> ); } // Use in components function WalletSection() { return ( <TonConnectButton /> ); }
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 <button onClick={handlePay}>Pay {amount} TON</button>; }
▼text复制代码### Mini App Monetization Making money from Mini Apps **When to use**: When planning Mini App revenue ```javascript ## 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!) ```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 <button onClick={share}>Invite Friends (+10 coins)</button>; }
Gamification for Retention
- Daily rewards
- Streak bonuses
- Leaderboards
- Achievement badges
- Referral bonuses
▼text复制代码## 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`
区块链
效率工具









