Telegram Mini App Architect

Name: Telegram Mini App Architect
Rating: 4.7 (196 reviews)
Author: davila7

telegrammini-apptonweb3mobile

★ 4.7 (196)⭐ 28.1k📄 MIT🕒 2026-06-16Source ↗

Install this skill

npx skills add davila7/claude-code-templates

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

What this skill does

•Telegram Web App API interface integration
•TON blockchain wallet connection and transactions
•Telegram Stars payment flow implementation
•User authentication via Telegram identity data
•Viral growth loop and referral system logic

When to use it

✓Building a new Telegram-native game or utility
✓Integrating TON Connect for crypto wallet authorization
✓Implementing monetization through Telegram Stars or in-app payments
✓Creating referral mechanics to drive app growth within chats

When not to use it

✕Building a standalone web site that does not interact with Telegram
✕Projects requiring high-performance desktop native APIs
✕Applications that do not benefit from the Telegram social graph

How to invoke it

Example prompts that trigger this skill:

“Create a new Telegram Mini App project structure.”
“Help me add TON Connect to my react Telegram mini app.”
“Implement a payment flow using Telegram Stars.”
“Guide me through creating a viral referral button for my app.”
“Check my code to ensure it follows mobile-first Telegram UX patterns.”

Example workflow

Initialize the project with the basic Telegram Web App script.
Integrate the Telegram object to capture user context.
Add TON Connect provider to support blockchain wallets.
Implement a payment button using either Stars or TON transactions.
Test the interface using mobile-first responsive design practices.

Prerequisites

–Node.js
–React knowledge
–Basic understanding of Telegram Bot API

Pitfalls & limitations

!Failing to respect Telegram's theme colors which ruins native look and feel
!Developing desktop-first UIs that ignore mobile touch target constraints
!Neglecting to validate initData on the backend to prevent spoofing

FAQ

What is the best way to handle payments?

For digital goods, use Telegram Stars (XTR) via the bot API. For decentralized finance, use TON Connect to trigger on-chain transactions.

Do I need a separate backend?

Yes, while the frontend handles user interactions, you need a secure server to validate user data and process sensitive transaction logic.

Can I use standard web frameworks?

Yes, React, Vue, or vanilla JavaScript work fine, provided you import the telegram-web-app.js script to access native bridging capabilities.

How it compares

Generic prompting often ignores the Telegram-specific theme and touch-target requirements; this skill enforces the specialized architecture needed for successful app integration.

Source & trust

⭐ 28k stars📄 MIT🕒 Updated 2026-06-16🛡 runs-shell, network

View original skill on GitHub →

From the 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,…”

View the full 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`

Quoted from davila7/claude-code-templates for reference — see the original for the authoritative, latest version.

📄 Full skill instructions — original source: davila7/claude-code-templates

The Telegram Mini App skill assists developers in creating web-based applications that operate inside the Telegram ecosystem. It simplifies the implementation of the Telegram Web App API, providing specialized guidance for integrating TON blockchain wallets, handling user authentication, and managing monetization via Telegram Stars or crypto payments. The skill enforces mobile-first design principles, ensuring your application adapts to Telegram's native themes and interaction paradigms. It is intended for developers building decentralized applications, interactive games, or utilities that require deep integration with the Telegram social graph. By following these patterns, you bridge the gap between traditional web development and the specific constraints of the Telegram client interface, enabling viral growth and native-like experiences for a massive global user base.

By davila7

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/telegram-mini-app/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/davila7/claude-code-templates/telegram-mini-app/SKILL.md
Cursor: ~/.cursor/skills/davila7/claude-code-templates/telegram-mini-app/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/davila7/claude-code-templates/telegram-mini-app/SKILL.md