telegram-mini-app
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 build...
Best use case
telegram-mini-app is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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 build...
Teams using telegram-mini-app should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/telegram-mini-app/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How telegram-mini-app Compares
| Feature / Agent | telegram-mini-app | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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 build...
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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' } }
]]
}
});
});
```
```
### 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>;
}
```
```
### 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
```
## 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`
## When to Use
This skill is applicable to execute the workflow or actions described in the overview.Related Skills
telegram
Integracao completa com Telegram Bot API. Setup com BotFather, mensagens, webhooks, inline keyboards, grupos, canais. Boilerplates Node.js e Python.
telegram-bot-builder
Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategie...
telegram-automation
Automate Telegram tasks via Rube MCP (Composio): send messages, manage chats, share photos/documents, and handle bot commands. Always search tools first for current schemas.
nerdzao-elite-gemini-high
Modo Elite Coder + UX Pixel-Perfect otimizado especificamente para Gemini 3.1 Pro High. Workflow completo com foco em qualidade máxima e eficiência de tokens.
gemini-api-integration
Use when integrating Google Gemini API into projects. Covers model selection, multimodal inputs, streaming, function calling, and production best practices.
gemini-api-dev
Use this skill when building applications with Gemini models, Gemini API, working with multimodal content (text, images, audio, video), implementing function calling, using structured outputs, or n...
zustand-store-ts
Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state/action separation. Use when building React state management, creating global stores, or implementing reacti...
zoom-automation
Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP (Composio). Always search tools first for current schemas.
zoho-crm-automation
Automate Zoho CRM tasks via Rube MCP (Composio): create/update records, search contacts, manage leads, and convert leads. Always search tools first for current schemas.
zod-validation-expert
Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC.
zeroize-audit
Detects missing zeroization of sensitive data in source code and identifies zeroization removed by compiler optimizations, with assembly-level analysis, and control-flow verification. Use for auditing C/C++/Rust code handling secrets, keys, passwords, or other sensitive data.
zendesk-automation
Automate Zendesk tasks via Rube MCP (Composio): tickets, users, organizations, replies. Always search tools first for current schemas.