Telegram Mini Apps: Complete Developer Guide

Telegram Mini Apps (formerly Web Apps) are lightweight web applications that run directly inside the Telegram interface. They allow developers to create rich, interactive experiences without users ever leaving the chat.

What Are Telegram Mini Apps?

Mini Apps are web pages loaded inside Telegram using the Bot API. They can access Telegram-native features like payments, user info, and haptic feedback. Think of them as full web apps embedded in a chat interface.

• Run in a built-in browser within Telegram
• Access user data (with permission) via the Telegram WebApp API
• Support payments through Telegram's payment system
• Work on iOS, Android, and Desktop

How Mini Apps Work

A Mini App is launched via a bot button (KeyboardButton or InlineKeyboardButton with type "web_app"). When tapped, Telegram opens your URL in a special WebView with access to the window.Telegram.WebApp JavaScript object.

Getting Started: Build Your First Mini App

1. Create a bot via @BotFather and get your token
2. Set up a web server with HTTPS (required). Use Cloudflare Pages, Vercel, or similar
3. Build your frontend using HTML/CSS/JS or any framework (React, Vue, Svelte)
4. Include the Telegram Web App script: <script src="https://telegram.org/js/telegram-web-app.js"></script>
5. Register the URL with BotFather using /newapp or set it as a menu button

Key API Features

• initData — Authenticated user info (user ID, name, language)
• MainButton — Native button at the bottom for primary actions
• BackButton — Navigation support within the app
• HapticFeedback — Vibration patterns for tactile responses
• CloudStorage — Per-user key-value storage
• BiometricManager — Fingerprint/Face ID authentication

Real-World Examples

• Wallet — TON cryptocurrency wallet built as a Mini App
• Notcoin — Tap-to-earn game with millions of users
• Fragment — Telegram's username and number marketplace
• Food delivery apps — Order food without leaving Telegram
• Booking systems — Schedule appointments in-chat

Best Practices

• Always validate initData on your server using HMAC-SHA256
• Design for mobile-first (most Telegram users are on phones)
• Use Telegram's native color scheme via CSS variables
• Keep load times under 2 seconds
• Test on all platforms (iOS, Android, Desktop)

Need your Telegram User ID for development? Use @userid_checkbot to get it instantly.

Frequently Asked Questions