Telegram Mini Apps

Web applications displayed inside Telegram’s WebView. Built with standard HTML/CSS/JS. Require a Telegram Bot as host.

Quick Start

1. Setup

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Or with @tma.js/sdk:

npm i @tma.js/sdk

2. Initialize

const tg = window.Telegram.WebApp
tg.ready()
tg.expand()

3. Create App via BotFather

1. /newbot — create bot
2. /newapp — create Mini App linked to bot
3. Set URL via /myapps > Edit link, or /setmenubutton

Result: https://t.me/{bot}/{app}?startapp={param}

Launch Methods

Essential Patterns

Theming — Match Telegram’s Look

body {
  background: var(--tg-theme-bg_color, #fff);
  color: var(--tg-theme-text_color, #000);
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

Always provide CSS fallbacks — app may load outside Telegram context during dev.

Listen for theme changes:

tg.onEvent('themeChanged', () => {
  document.body.className = tg.colorScheme // "light" | "dark"
})

Safe Areas — Prevent Content Clipping

.app {
  padding-top: calc(var(--tg-content-safe-area-inset-top, 0px) + var(--tg-safe-area-inset-top, 0px));
  padding-bottom: var(--tg-safe-area-inset-bottom, 0px);
  padding-left: var(--tg-safe-area-inset-left, 0px);
  padding-right: var(--tg-safe-area-inset-right, 0px);
}

Viewport — Handle Mobile Bottom Sheet

tg.expand() // maximize height

tg.onEvent('viewportChanged', ({ isStateStable }) => {
  if (isStateStable) {
    // Safe to adjust layout — user stopped dragging
  }
})

// Prevent accidental close via swipe on scrollable content
tg.disableVerticalSwipes()

Main Button — Primary CTA

const btn = tg.MainButton
btn.setText('Submit')
btn.show()
btn.onClick(() => {
  btn.showProgress(true)
  submit().finally(() => btn.hideProgress())
})

Back Button — In-App Navigation

tg.BackButton.show()
tg.BackButton.onClick(() => router.back())
// Hide when on root page
tg.BackButton.hide()

User Identity

const user = tg.initDataUnsafe.user
// { id, first_name, last_name?, username?, language_code?, is_premium?, photo_url? }

// IMPORTANT: always validate initData server-side before trusting user identity
// Send raw init data to your server:
fetch('/api', { headers: { Authorization: `tma ${tg.initData}` } })

Haptic Feedback

tg.HapticFeedback.impactOccurred('medium')      // button tap
tg.HapticFeedback.notificationOccurred('success') // action complete
tg.HapticFeedback.selectionChanged()              // picker change

Popups

tg.showPopup({
  title: 'Confirm',
  message: 'Delete this item?',
  buttons: [
    { id: 'del', type: 'destructive', text: 'Delete' },
    { id: 'no', type: 'cancel' },
  ]
}, (id) => { if (id === 'del') doDelete() })

Closing Behavior

tg.enableClosingConfirmation()  // ask before close (unsaved changes)
tg.disableClosingConfirmation()

References

Detailed API docs organized by topic. Read as needed.

• api-methods.md — All 60+ WebApp methods with parameters, version requirements, and code examples. Covers: lifecycle, viewport, navigation, buttons, popups, theming, storage, permissions, sharing, sensors, biometrics, QR, clipboard, fullscreen, orientation, payments.

• events.md — All events sent from Telegram to the Mini App. Covers: lifecycle, button presses, viewport/layout, theme, popups, permissions, sharing, payments, QR, biometrics, sensors, location, storage, home screen, fullscreen.

• init-data.md — Init data structure, WebAppUser/WebAppChat objects, HMAC-SHA256 and Ed25519 validation algorithms with code examples, server-side auth patterns.

• debugging.md — Platform-specific debug setup (Desktop, macOS, Android, iOS), Eruda integration, test environment access, common issues and fixes.

Platform Considerations

• 6 Telegram clients with varying feature support — check tg.version before using newer APIs
• Mobile opens as bottom sheet — call expand() early, handle unstable viewport
• Desktop/Web opens maximized — expand() is a no-op
• Test environment allows HTTP and direct IPs — use for dev, create separate bot there
• HTTPS required in production
• Scaffold new projects with: npx @tma.js/create-mini-app@latest

Version Compatibility

Use tg.version to check API availability. Key version milestones: