Telegram Mini App Development Guide: From Zero to Live in One Day
Telegram Mini Apps run inside Telegram's chat interface. No App Store submission. No Play Store review. No separate download. A user taps a link, the app opens inside Telegram, and it works on iOS, Android, desktop, and web — all from one codebase. Over a billion monthly active users can reach it without installing anything.
I built and shipped my first Telegram Mini App — a number speed game called SpeedTap — in one day. No prior Telegram development experience. Claude Code handled the implementation. This guide covers the full process, including the platform-specific problems that no tutorial warned me about.
What a Telegram Mini App Actually Is
A Telegram Mini App is a web page that loads inside Telegram's built-in browser (WebView). It's standard HTML, CSS, and JavaScript. You can use any frontend framework — React, Vue, vanilla JS. The app gets displayed inside the Telegram chat window, and Telegram provides a JavaScript SDK for features like user authentication, haptic feedback, sharing, and payments.
The minimum requirements to launch one:
You register a bot with @BotFather, set the web app URL, and it's live. Users access it through the bot or through direct links. There's no review process for the initial launch — the app goes live the moment you configure the URL.
The Development Flow
The architecture is a normal web app with one addition: Telegram's WebApp SDK gives you access to the user's Telegram identity, the native share function, and the payment system.
For SpeedTap, the stack was:
Frontend: Vanilla JavaScript modules (no framework). Hosted on Cloudflare Pages with automatic deployment from GitHub. Total hosting cost: $0.
Backend: FastAPI on Oracle Cloud free tier. Handles user scores, leaderboards, daily challenges, and anti-cheat validation. Total hosting cost: $0.
Bot: A separate Python process (python-telegram-bot library) that handles bot commands, notifications, and payment webhooks. Runs as a systemd service on the same Oracle instance.
Database: SQLite. SpeedTap uses 12 tables — users, scores, daily challenges, duels, purchases, referrals, achievements, settings, notifications, play counts, challenge codes, and admin stats. All in a single 2 MB file.
The entire project — frontend, backend, bot, database schema — was generated by Claude Code from a single spec document. I described the game rules, the screens, and the data model. Claude Code produced a working project that ran on the first try.
Three Platform Quirks That Waste Hours
The game logic worked immediately. Shipping it took another few hours because of Telegram-specific issues that don't appear in regular web development.
WebView caching ignores your headers. Telegram's mobile WebView caches JavaScript files aggressively. HTTP cache-control headers — the standard way to tell browsers to fetch fresh files — get ignored completely. You push a fix to Cloudflare, reload the app, and the old JavaScript still runs. CSS changes appear; JS changes don't.
The only reliable fix: version parameters on every import statement.
Telegram injects CSS that breaks your design. Telegram sets CSS variables based on the user's theme — light or dark. If you don't override them, light-mode users might see white text on white backgrounds. My game grid was literally invisible to anyone using Telegram in light mode.
Fix: force one theme. Set color-scheme: dark in your CSS, override all Telegram theme variables with your own colors. Don't try to support both themes unless you're willing to test every element in both.
iOS startapp parameter is broken. Telegram's iOS app has a documented bug where initDataUnsafe.start_param returns undefined for Mini App direct links. This has been reported since 2023 and remains unfixed. If your app relies on URL parameters to route users to specific content (like a challenge invite), you need a fallback. I ended up using a manual 4-character code system instead of URL-based routing because no URL-based approach worked reliably on iOS.
Monetization: What Actually Works
Telegram Mini Apps have three monetization paths. I've tested two of them.
Ads via Monetag. Monetag is a Telegram-native ad network. Sign up as a publisher, enter your bot username, paste the SDK script into your HTML, get a zone ID. No business registration required. Minimum withdrawal: $5. The integration takes about 15 minutes.
My results with SpeedTap: CPM around $0.34 with 79 users. That's below industry benchmarks ($2-6 for rewarded interstitials) because Monetag's algorithm needs thousands of impressions before it optimizes. At scale, CPM should climb. At 79 users, it's pennies.
The critical rule for ad placement: never during gameplay. Ads at natural pause points only — after three free plays, after game over, after completing a daily challenge. If the ad fails to load, the game continues silently. Users should never wait for an ad that isn't coming.
Telegram Stars. Telegram's built-in virtual currency. Users buy Stars through Apple or Google IAP, spend them inside Mini Apps. 1 Star ≈ $0.013. The developer receives Stars in their bot balance, withdrawable after 21 days. I charge 50 Stars to unlock premium difficulty modes.
Honest result: zero real purchases from users. With 79 users and a free alternative (invite 5 friends to unlock the same modes), nobody chose to pay. Sample too small to draw conclusions.
AdsGram (user acquisition, not monetization). Telegram-native ad platform for promoting Mini Apps. I ran a $10 test campaign: 3,237 impressions, 168 clicks, 77 new users at $0.13 per install. For comparison, mobile game CPI typically ranges $0.50-$5+. The acquisition cost was genuinely cheap.
The Apps Center: Optional but Valuable
Telegram has an official app directory — the Apps Center at tapps.center — with around 178K monthly browsers. Listing isn't automatic. You submit your app and it gets reviewed.
SpeedTap got rejected on the first submission. The feedback: "Enhance design, add distinctive features, improve social mechanics, consider Stars payments." That rejection became the spec for Phase 2 — difficulty modes, 1v1 challenges, and Stars integration all came from the reviewer's four sentences.
You don't need Apps Center approval to operate. Your Mini App works fine without it. But the directory is free organic discovery — worth applying for once your app is polished enough.
Is It Worth Building On?
Telegram Mini Apps have a genuine distribution advantage: zero install friction, one billion monthly users, and a platform that wants third-party apps to succeed. The developer experience has real rough edges — the caching, the iOS bugs, the sparse documentation — but the barrier to going live is the lowest of any major platform.
For solo builders, the math is straightforward. You can go from idea to live app in a day, with $0 infrastructure cost, and start earning ad revenue without a business registration. Whether the revenue justifies the effort depends on whether you can find an audience — but the cost of trying is close to zero.
Related guides:
- Building a Full-Stack App with Claude Code in One Day
- Oracle Cloud Always Free ARM Instance: Setup Guide
- How I Cut My Claude API Costs by 80%
Disclaimer: This blog documents practical workflows based on personal experience. Nothing here is financial, legal, or professional advice.
Comments
Post a Comment