What a Telegram Mini App Actually Is - and When I Would Build One

A Telegram Mini App is not a bot with prettier buttons. It is a real web application - HTML, CSS, JavaScript - that Telegram opens in a sheet inside the chat. The user never leaves the messenger, never visits an app store, and often never types a password. That is the product: a job done where the conversation already is.

People still say “Telegram Web App” because that was the old name. Same thing: a HTTPS page plus the WebApp SDK plus a bot that opens it. If you paste a marketing site into that webview, you do not have a Mini App. You have a cramped website with a Telegram header. This article is how I would actually treat the surface.

1. Mini App vs bot vs website vs store app

These four surfaces solve different jobs. Mixing them up is how you get a bot that tries to be a shop, or a Mini App that tries to rank on Google.

• Bot: chat UI. Great for commands, alerts, one-shot payments, “send me this PDF.” Terrible for catalogs, calendars, and multi-step forms.
• Website: public URL, SEO, shareable links, desktop. The front door for people who are not already in your Telegram.
• Store app: install, push, offline, App Store tax. Right when you need OS privileges. Wrong when the job is “book a slot in 40 seconds.”
• Mini App: full UI inside Telegram, identity from the chat, payments via Stars or invoices, updates without a store review. The product lives where the customer already chats with you.

2. How it is actually wired

Three pieces, not one. Miss any of them and you have a demo, not a product.

• A bot. It owns the menu button, KeyboardButton web_app, inline button, or direct link (t.me/bot/app). Without a bot there is nothing to open the sheet.
• A HTTPS web app. Telegram loads your URL in a webview. Next.js on Vercel (or any HTTPS host) is fine. HTTP and localhost tricks belong in development only.
• The WebApp SDK (`window.Telegram.WebApp`). Theme, viewport, MainButton, BackButton, haptic, CloudStorage, invoice, the user object. Without it you are guessing CSS in the dark.

3. Identity: initData is not a login screen

When Telegram opens your page it appends signed `initData`: user id, name, language, optional query, a hash. That is the session. The user already proved they own that Telegram account by being inside the app. Do not bolt on “sign in with email” unless you must bind an existing cabinet.

Never trust `initData` in the browser. Anyone can open DevTools and fake a user object. The server must HMAC-validate the hash with the bot token, check `auth_date` is fresh, then mint your own session cookie or JWT. If you skip that step, you do not have auth. You have a costume.

4. UX that does not feel like a website in a drawer

Telegram already has chrome: a grab handle, safe areas, a theme that follows light/dark. Fight it and the app feels foreign. Use it and it feels native.

• MainButton is the primary action - pay, book, submit. A CSS button at the bottom will sit under the home indicator and look like a clone.
• BackButton for nested screens. The Telegram swipe-down closes the Mini App - do not steal that gesture for “previous step.”
• Read `themeParams` and `colorScheme`. Hard-coded white pages in dark Telegram look like a bug.
• Viewport is not `100vh`. Use `viewportStableHeight` and expand when you need the full sheet. Test on iOS and Android - they disagree.

5. When I would actually ship a Mini App

I would build one when the customer is already in Telegram - or will be, because that is how this business talks - and the job needs a real UI, not a chain of messages.

• Booking with a calendar, not “reply with a date.” Shops with filters. Course cabinets. Calculators that become a lead. Loyalty cards. Internal tools for a team that already lives in a group.
• Payments that should not leave the chat: Telegram Stars, invoices, or a checkout you already run - opened from the Mini App, confirmed back in the bot.

6. When I would refuse

A Mini App does not replace a website. It does not rank. It does not work well as the only door if half of the buyers arrive from Google. It is also a bad place to dump a desktop CRM.

• SEO, blog, public catalog, “about us,” hiring pages - that is a website. Link to the Mini App from there if the job continues in chat.
• Heavy graphics, huge tables, multi-window admin. The sheet is a phone-first surface. Build a real admin on the web.
• If the only requirement is “we heard Mini Apps are trending” and there is no Telegram audience - start with a site and a bot that does one job.

7. The stack I would open with in 2026

Same discipline as an MVP: one codebase that can also be the website later, a boring database, a bot that only opens the door and confirms payments.

• Next.js + TypeScript + Tailwind for the UI. One app: Mini App routes and, if needed, the public marketing site.
• PostgreSQL as the source of truth. Users keyed by Telegram id. Redis if you need rate limits or short-lived drafts.
• A small bot (grammY or Telegraf) for Menu Button, invoices, and post-payment messages. Do not put business logic only in the bot if the Mini App also needs it - share a module.
• Validate initData on the server on every privileged request. Store nothing secret in the webview.

The Mini App is a door, not a brand

Treat it as a product surface with a contract: open fast, look like Telegram, prove the user on the server, finish one job, send the receipt back into the chat. If you need discovery, SEO, and a story for strangers - that is still a website. If you need a conversation plus a real UI - that is a Mini App. I would ship the second when the audience is already in the messenger. I would not ship it because the old name “Web App” sounded cheaper than an App Store build.