telegram-mini-app
Documentation & Productivité"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."
Documentation
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
Patterns
Mini App Setup
Getting started with Telegram Mini Apps
When to use: When starting a new Mini App
## Mini App Setup
### Basic Structure
### 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
}
### 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
### Setupnpm install @tonconnect/ui-react
### React Integrationimport { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';
// Wrap app
function App() {
return (
);
}
// Use in components
function WalletSection() {
return (
);
}
### Manifest File{
"url": "https://your-app.com",
"name": "Your Mini App",
"iconUrl": "https://your-app.com/icon.png"
}
### Send TON Transactionimport { 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 ;
}
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 ;
}
### Gamification for Retention
- Daily rewards
- Streak bonuses
- Leaderboards
- Achievement badges
- Referral bonusesAnti-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
Compétences similaires
Explorez d'autres agents de la catégorie Documentation & Productivité
ai-agents-architect
"Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool use, function calling."
documentation-generation-doc-generate
"You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI-powered analysis and industry best practices."
docx
"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"