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...

techwavedev Updated Sep 10, 2026

Integrations & APIs

Install

Press C to copy

$ npx skillmds@latest add techwavedev/telegram-mini-app

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/techwavedev/telegram-mini-app.svg)](https://skillmd.com/skills/techwavedev/telegram-mini-app)

Trust & safety

Audits pending

Not yet audited · commit 96103c0

Permissions this skill uses

Makes network calls
The instructions fetch remote URLs or call external services.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

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

## 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 {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 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.

---

<!-- AGI-INTEGRATION-START -->

## AGI Framework Integration

> **Adapted for [@techwavedev/agi-agent-kit](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)**
> Original source: [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)

### Memory-First Protocol

Retrieve prior API design decisions, database schema choices, and error handling patterns. Cache API response templates for consistent error formatting.

```bash
# Check for prior backend/API context before starting
python3 execution/memory_manager.py auto --query "API design patterns and architecture decisions for Telegram Mini App"

Storing Results

After completing work, store backend/API decisions for future sessions:

python3 execution/memory_manager.py store \
  --content "API architecture: REST with HATEOAS, JWT auth, rate limiting at 100 req/min per tenant" \
  --type decision --project <project> \
  --tags telegram-mini-app backend

Multi-Agent Collaboration

Share API contract changes with frontend agents so they update their client code, and with QA agents for test coverage.

python3 execution/cross_agent_context.py store \
  --agent "<your-agent>" \
  --action "Implemented API endpoints — 5 new routes with OpenAPI spec and integration tests" \
  --project <project>

Agent Team: Code Review

After implementation, dispatch code_review_team for two-stage review (spec compliance + code quality) before merging.

---name: telegram-mini-appdescription: 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...---# Telegram Mini App**Role**: Telegram Mini App ArchitectYou build apps where 800M+ Telegram users already are. You understandthe Mini App ecosystem is exploding - games, DeFi, utilities, socialapps. You know TON blockchain and how to monetize with crypto. Youdesign 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 SetupGetting 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.jsexport 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.jsxfunction App() { const { tg, user, expand, ready } = useTelegram(); useEffect(() => { ready(); expand(); }, []); return <div>Hello, {user?.first_name}</div>;}```### Bot Integration```javascript// Bot sends Mini Appbot.command('app', (ctx) => { ctx.reply('Open the app:', { reply_markup: { inline_keyboard: [[ { text: '🚀 Open App', web_app: { url: 'https://your-app.com' } } ]] } });});``````### TON Connect IntegrationWallet connection for TON blockchain**When to use**: When building Web3 Mini Apps```python## TON Connect Integration### Setup```bashnpm install @tonconnect/ui-react```### React Integration```jsximport { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';// Wrap appfunction App() { return ( <TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json"> <MainApp /> </TonConnectUIProvider> );}// Use in componentsfunction 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```jsximport { 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 MonetizationMaking 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 botbot.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 systemfunction 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 SkillsWorks well with: `telegram-bot-builder`, `frontend`, `blockchain-defi`, `viral-generator-builder`## When to UseThis skill is applicable to execute the workflow or actions described in the overview.---## AGI Framework Integration> **Adapted for [@techwavedev/agi-agent-kit](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)**> Original source: [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)### Memory-First ProtocolRetrieve prior API design decisions, database schema choices, and error handling patterns. Cache API response templates for consistent error formatting.```bash# Check for prior backend/API context before startingpython3 execution/memory_manager.py auto --query "API design patterns and architecture decisions for Telegram Mini App"```### Storing ResultsAfter completing work, store backend/API decisions for future sessions:```bashpython3 execution/memory_manager.py store \ --content "API architecture: REST with HATEOAS, JWT auth, rate limiting at 100 req/min per tenant" \ --type decision --project <project> \ --tags telegram-mini-app backend```### Multi-Agent CollaborationShare API contract changes with frontend agents so they update their client code, and with QA agents for test coverage.```bashpython3 execution/cross_agent_context.py store \ --agent "<your-agent>" \ --action "Implemented API endpoints — 5 new routes with OpenAPI spec and integration tests" \ --project <project>```### Agent Team: Code ReviewAfter implementation, dispatch `code_review_team` for two-stage review (spec compliance + code quality) before merging.

techwavedev/agi-agent-kit/tree/main/templates/skills/extended/backend/telegram-mini-app commit 96103c0fbd

Frequently asked questions

npx skillmds@latest add techwavedev/telegram-mini-app