Telegram Mini App
FreeBuild native-like apps for Telegram with ease.
Free ยท Opens the source repo
What Telegram Mini App does
The Telegram Mini App skill is designed for developers looking to create web applications that operate seamlessly within the Telegram ecosystem. With over 800 million users, Telegram Mini Apps (TWA) provide a unique opportunity to engage users through a native-like experience. This skill covers essential aspects of Mini App development, including the Telegram Web App API, user authentication, in-app payments, and integration with the TON blockchain. It is particularly useful for those interested in building applications that can monetize effectively within Telegram's platform.
This skill offers comprehensive guidance on the architecture and UX patterns specific to Telegram, ensuring that your app feels intuitive and familiar to users. You will learn how to set up a Mini App, integrate with Telegram's APIs, and leverage the TON ecosystem for blockchain functionalities. The provided code snippets and examples make it easy to get started, whether you're building a simple utility app or a more complex decentralized finance (DeFi) application.
Moreover, the skill includes strategies for monetization, allowing developers to explore various revenue models such as in-app purchases, ads, and even NFT sales. By following the best practices outlined in the skill, you can avoid common pitfalls and create engaging applications that retain users and encourage sharing. This skill is ideal for developers and designers who want to tap into the growing demand for Mini Apps within Telegram and build applications that resonate with the platform's user base.
When to use it
Use this skill when starting a new Telegram Mini App or when you want to integrate with Telegram's Web App API and TON blockchain.
When not to use it
This skill may not be suitable for traditional web app development outside the Telegram ecosystem or for apps that do not require integration with Telegram's features.
What you can build with it
Starting a New Mini App
When you want to build a new Mini App for Telegram, this skill provides the foundational knowledge and code examples to get started.
Integrating with TON Blockchain
If you're developing a Web3 Mini App, this skill guides you through the integration process with the TON blockchain.
Monetizing Your Mini App
Learn various monetization strategies to generate revenue from your Telegram Mini App, including in-app purchases and ads.
How to install Telegram Mini App
View source1. Install with the skills CLI
npx skills add davila7/claude-code-templates/telegram-mini-app --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by davila7Telegram 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
<!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
// 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
// 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
## TON Connect Integration
### Setup
```bash
npm install @tonconnect/ui-react
React Integration
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
{
"url": "https://your-app.com",
"name": "Your Mini App",
"iconUrl": "https://your-app.com/icon.png"
}
Send TON Transaction
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>;
}
### 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
// 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
## 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`
Frequently asked questions about Telegram Mini App
Similar skills
Playwright Component Testing
Test React and Vue components in isolation with Playwright.
Fluent UI Blazor
Integrate Fluent UI components in Blazor applications effortlessly.
Build MCP App
Create interactive UI widgets for MCP servers.
Web Design Reviewer
Identify and fix design issues in websites efficiently.
Markstream Install
Seamlessly integrate Markstream for Markdown rendering.
GSAP & Framer Scroll Animation
Create advanced scroll animations effortlessly.