How to Build a Telegram Mini App: A Step-by-Step Guide

A Telegram Mini App is a web app that opens inside Telegram. To build one, you create a bot with @BotFather, build a mobile-first web app hosted over HTTPS, include Telegram's Mini App script so the page can talk to Telegram, and register the app's address with your bot so users can open it from a button or a link. Then you verify each user on your server, match Telegram's theme, and test on every platform before launch.

This guide walks through those steps in order, explains the decisions at each one, and covers the parts beginners usually get wrong: verifying users, payments for digital goods, and testing inside the Telegram app rather than a browser. It describes calls and settings in words rather than code, so it suits both developers and the people managing them.

What a Mini App is, technically

A Mini App is an ordinary website, written in HTML, CSS and JavaScript, shown in a web view inside Telegram. What makes it more than a link is a small JavaScript library that Telegram provides. When your page loads it, the page gets an object representing the Mini App, through which it can:

• Read who opened it and from where, as signed launch data.
• Read the user's Telegram theme colours so your page matches.
• Show Telegram's own main button at the bottom of the screen and a back button at the top.
• Expand to full height, and on recent versions go full screen.
• Trigger haptic feedback, open links, open Telegram links, or close itself.
• Store small amounts of data per user in Telegram's cloud storage.
• Ask the user to share their phone number, or to allow the bot to message them.
• Open an invoice so the user can pay.

Telegram's developer documentation for Mini Apps lists every method and event. It changes regularly as Telegram adds features, so treat it as the reference and check its changelog before relying on something new.

For a non-technical overview of what Mini Apps are used for, read Telegram Mini Apps explained.

What a Mini App is not

• Not a native app. It runs in Telegram's web view, so it has the abilities of a web page plus what Telegram's library adds. It cannot use arbitrary phone features.
• Not hosted by Telegram by default. You host the web app yourself, on any server or static hosting that serves HTTPS.
• Not the bot. The bot and the Mini App are linked, but the bot is a separate program that receives messages and updates. Many Mini Apps need a small bot backend, for example to send invoices or messages.

Before you start

1. Write down what the app does in one sentence. "Book a table", "Track my orders", "Play a short puzzle". A Mini App succeeds when it does one job fast.
2. Decide whether you need a backend. A simple calculator can be static files. Anything with accounts, orders, scores shared between users or payments needs a server.
3. Decide whether money is involved. Selling digital goods or services inside a Mini App has specific rules, covered below.
4. Pick a web stack you know. Any framework works, or none. Telegram does not require a particular one.
5. Have HTTPS hosting ready. Telegram requires a secure address for the app.
6. Read Telegram's Mini App design guidelines and developer terms. They describe what users expect and what Telegram does not allow.

Step 1: Create the bot

Every Mini App belongs to a bot.

1. Open a chat with @BotFather in Telegram.
2. Create a new bot and give it a display name and a username ending in "bot".
3. Save the token BotFather gives you somewhere private. Anyone with the token controls the bot. Never put it in your web app's front-end code.
4. Set the bot's description, about text and picture, since users see them when they first open it.

Our guide to creating a bot with BotFather covers this step in detail.

Step 2: Build the web app

Start mobile-first

Most users open Mini Apps on a phone, in a panel that starts at partial height and can be expanded. Design for a narrow screen first.

1. Use a responsive layout that works from small phones upwards.
2. Keep the first screen useful: the main action should be visible without scrolling.
3. Use large touch targets and readable text.
4. Load fast. Every second of blank screen inside a chat feels long. Keep the first bundle small and load the rest later.

Load Telegram's library

Include Telegram's Mini App script in your page, loaded from Telegram's own domain as the documentation describes, before your own scripts run. Once it loads, your code can reach the Mini App object.

The first calls most apps make are:

1. Tell Telegram the app is ready, which hides the loading placeholder. Call it once your first screen is drawn, not before.
2. Expand the app if your layout needs the full height.
3. Read the theme parameters and apply them.

Use Telegram's interface pieces

Telegram gives you native controls that users already know.

• The main button (also called the bottom button) sits at the bottom of the screen. Use it for the one primary action, such as "Checkout" or "Save". You set its text and colour, show or hide it, and listen for taps.
• A secondary button can sit beside or above it on recent versions, for a second action.
• The back button appears in Telegram's header. Show it when the user is on a sub-screen, and handle its tap to go back within your app. Without it, the only way out is closing the app.
• Popups and confirmations use Telegram's own dialogs, which look native on each platform.
• Haptic feedback gives a small vibration on taps and results, which makes the app feel native on phones.

Using these instead of your own fixed buttons makes the app feel like part of Telegram and avoids clashes with the system's own controls.

Step 3: Match Telegram's look

Telegram passes the user's theme colours to your app: background, text, hint, link, button and button text colours, and more. They change when the user switches between light and dark mode.

1. Read the theme parameters at start-up and apply them as your page's colours.
2. Listen for the theme-changed event and update when it fires.
3. Use the colours Telegram provides for the header and background so the app blends with the chat.
4. Respect the safe area on phones with notches and rounded corners, which the library reports, especially in full-screen mode.
5. Listen for viewport changes. The visible height changes when the user expands the panel or the keyboard opens, and your layout should keep the main content in view.

A Mini App that ignores the theme looks broken in dark mode, which many users use.

Step 4: Decide how users open it

There are several launch points, and each passes slightly different context to your app. You can use more than one.

The main Mini App

You can set one main Mini App for your bot in @BotFather. Telegram then shows a prominent button to open it on the bot's profile, and the documentation says you can add demo videos and screenshots there too. This is the main entrance for most apps.

The menu button

The menu button sits next to the message field in a private chat with your bot. You can set it to open your Mini App, so users who are chatting with the bot are one tap away.

Direct links

A direct link opens your Mini App from anywhere a link can go: a channel post, a website, a QR code. Telegram's documentation describes creating a named app for your bot through @BotFather, which gives it a t.me link with the bot's username and the app's short name. You can add a start parameter to the link, which your app receives at launch, to open a specific screen or track where users came from.

Buttons in the bot's messages

Your bot can send messages with an inline button that opens the Mini App, or a keyboard button that opens it and lets the app send data back to the bot. Telegram's Bot API limits the dedicated Mini App button to private chats between the user and the bot; in channels and groups, use a URL button with the direct link instead.

Inline mode and attachment menu

A bot in inline mode can offer a button to open its Mini App from the inline results, and some bots can appear in the attachment menu. These are more advanced; check the documentation for current availability.

Step 5: Know who the user is, and prove it

When your app opens, Telegram passes launch data: the user's ID, name, language, sometimes their username and photo, the chat context, the start parameter, an authentication date and a signature. The library gives this to your page in two forms: a raw string, and a parsed object marked as unsafe.

The "unsafe" label matters. Anything running in the browser can be changed by the user. Use the parsed object only for display, such as showing the user's first name. For anything that counts, such as loading their orders or crediting a purchase, your server must verify the raw string.

How verification works, in words

Telegram's documentation describes the check like this:

1. Your front-end sends the raw launch string to your server with each request, for example in a header.
2. The server splits the string into fields, removes the hash field, sorts the remaining fields alphabetically, and joins them as lines of "key equals value". This is the data-check string.
3. The server computes a secret key: an HMAC-SHA-256 of your bot's token, using the constant text "WebAppData" as the key.
4. The server computes an HMAC-SHA-256 of the data-check string using that secret key, and writes it as hexadecimal.
5. If the result matches the hash field, the data really came from Telegram for your bot.
6. The server also checks the authentication date and refuses launch data that is too old, so a captured string cannot be replayed indefinitely.

Two details cause most failures. The secret key is derived with "WebAppData" as the key and the token as the message, not the other way round; swapping them produces a plausible-looking value that never matches. And Telegram's older login widget uses a different secret derivation, so code copied from a login widget example will not work here.

Telegram also documents a way for third parties to check launch data without your bot token, using a signature field verified with Telegram's public key. Use it if another service needs to trust your users.

Sessions

After verifying, many apps create their own short session on the server so they do not verify on every request. Keep that session tied to the Telegram user ID you verified, and expire it. Never accept a user ID sent separately from the signed data.

If you also want users to sign in to a normal website with Telegram, that is the separate login widget feature, with its own verification method.

Step 6: Store data

You have two places to keep data.

• Telegram cloud storage. Telegram's library offers a small key-value store per user, per bot. It is handy for preferences and small state that should follow the user between devices. It is not a database: keep it to small values and do not store secrets in it.
• Your own backend. For anything shared between users, large, or important, use your own database, keyed by the verified Telegram user ID.

Recent versions of the library add device-level storage options as well. Check the documentation for what they guarantee before relying on them for anything sensitive.

Step 7: Talk to the bot and to the user

A Mini App often works together with its bot.

• Send data to the bot. When opened from a keyboard button, the app can send a small piece of data back to the bot, which arrives as a message and closes the app. Good for simple forms.
• Have the bot message the user. A bot can only message a user who has started it or allowed it. A Mini App can ask the user for permission for the bot to write to them, which you need for order confirmations and reminders.
• Receive updates. Your bot's backend receives updates through polling or a webhook. For a production app, a webhook on your server is usual. See setting a webhook for a Telegram bot.
• Open links correctly. Use the library's method for opening external links and its separate method for Telegram links, rather than plain links, so they open the right way on every platform.

Step 8: Take payments

Digital goods and services: Telegram Stars

Telegram requires digital goods and services sold inside Mini Apps and bots to be paid in Telegram Stars. That covers things like in-app items, premium features, content and subscriptions.

The flow, described in words:

1. Your bot's backend creates an invoice link through the Bot API, with the currency set to Telegram Stars, a title, a description and a price in Stars.
2. The Mini App opens the invoice through the library's invoice method.
3. Telegram shows its own payment sheet. The user confirms.
4. Before charging, Telegram asks your bot to confirm the order in a pre-checkout step. Check the order is still valid and answer quickly.
5. After payment, your bot receives a successful-payment update. Deliver the item based on that update, not on anything the Mini App says, because the front-end can be faked.

Our guide to bot payments for developers goes deeper, including refunds.

Physical goods

For physical goods and real-world services, bots can use supported payment providers through Telegram's payments platform, or link out to your own checkout. Check Telegram's current rules for your case.

TON and wallets

Some Mini Apps connect to a user's TON wallet, for example to accept TON or show collectibles. That uses the TON Connect protocol, not the Stars flow. Our guide to connecting a TON wallet with TON Connect explains what the user sees. Crypto features bring extra legal and safety responsibilities; take advice for your situation.

Security checklist before launch

Mini Apps run on the open web and handle real accounts, so a short review before launch pays off.

1. Verify launch data on every sensitive request, or create a server session only after verifying it. Reject data whose authentication date is too old.
2. Keep the bot token on the server only, in an environment variable or secret store, never in the repository or the page.
3. Validate every input on the server. Prices, quantities and item IDs come from your database, never from what the page sends.
4. Make purchase delivery idempotent. Telegram may deliver an update more than once; a payment should credit the user exactly once.
5. Use HTTPS everywhere, including the API your front-end calls.
6. Limit what you collect. Store the Telegram user ID and what the app genuinely needs. Say so in your privacy policy.
7. Rate-limit your API. Anyone can open your app and call your endpoints repeatedly.
8. Never ask users for their Telegram login code or password. A Mini App never needs them, and asking would make your app look exactly like a phishing page.

Performance tips that matter inside Telegram

Users open Mini Apps from chats, often on mobile data, and close them quickly if nothing appears.

• Show something immediately. Render a light first screen, call ready, and load the rest after.
• Keep the first download small. Split large libraries and load heavy features only when the user reaches them.
• Cache static files with long cache times and versioned file names.
• Avoid layout jumps when the panel expands or the keyboard opens; reserve space for the main button.
• Handle a lost connection. Show a clear message and a retry option rather than a spinner that never ends.

Step 9: Register and configure in BotFather

With the app hosted, connect it to the bot.

1. Open @BotFather. Recent versions offer a BotFather Mini App with the same functions as the chat commands, in a more visual layout.
2. Select your bot.
3. Set the main Mini App's address, and add screenshots or a demo video if you want them on the bot's profile.
4. Optionally set the menu button to open the Mini App.
5. Optionally create a named app to get a direct link, as described in Step 4.
6. Check the bot's privacy and payment settings if you take payments.

Keep the app on the domain you registered. Telegram has been tightening which web origins may call Mini App methods, so an app that loads parts of itself from other domains may find those calls refused.

Step 10: Test properly

A Mini App that works in a desktop browser can still fail inside Telegram. Test where users are.

1. Test on Android, iPhone and Telegram Desktop. Each uses a different web view with different quirks: scrolling, keyboards and safe areas differ most.
2. Test light and dark themes by switching the phone's theme while the app is open.
3. Test every launch point: profile button, menu button, direct link with and without a start parameter.
4. Test with a fresh account, so you see the first-time flow, permission prompts and empty states.
5. Use debugging tools. Telegram's documentation explains how to inspect the web view on each platform, for example through the browser's remote debugging on Android and through an option in Telegram Desktop's advanced settings. Search the documentation for its debugging section; the steps change between versions.
6. Use Telegram's test environment if you need to test payments or flows without touching production accounts. It is a separate server with separate accounts.
7. Test slow networks. Throttle your connection and watch what users see while data loads.

Step 11: Launch and grow

1. Write a clear bot description and profile. It is the first thing users see. Say what the app does in a sentence.
2. Prepare the first screen for strangers. Someone arriving from a link knows nothing; explain the app in a line and offer the main action.
3. Use direct links with start parameters in posts, ads and QR codes, so you know which sources work.
4. Add a privacy policy that says what you collect and why. Telegram expects one, and users deserve one.
5. Watch your server and errors after launch. Real users find paths you never tested.

Promoting an app is its own job; see how to promote a Mini App or bot. If you list a channel or bot connected to the app in our directory, every submission is reviewed by a person before it appears; you can submit it here.

After launch: what to improve first

The first weeks show where users drop off. Three places usually deserve attention first:

• The first screen. If many people open the app and leave without acting, the first screen is not explaining itself. Test a shorter headline and a clearer main button.
• Permission prompts. Asking for contact sharing or bot messages too early makes people refuse. Ask at the moment the permission is clearly useful, such as right after a booking.
• Error paths. Read your server's errors daily at first. A failure that hits one user in a hundred is still a failure for every one of them.

Worked example: a table booking Mini App

This is an illustration of how the pieces fit, not a template you must follow.

A café wants customers to book a table from its Telegram channel.

1. The developer creates a bot for the café in @BotFather.
2. She builds a small web app: pick a date, a time and a party size, then confirm. It uses Telegram's theme colours and the main button for "Book".
3. The app's server verifies the launch data on every request and stores bookings against the verified Telegram user ID.
4. When the user taps "Book", the app asks permission for the bot to message them. The server saves the booking and the bot sends a confirmation message.
5. The café's channel posts a link button with the app's direct link and a start parameter naming the channel, so the café can see bookings that came from it.
6. Before launch, she tests on an Android phone, an iPhone and Telegram Desktop, in both themes, and fixes a layout bug where the keyboard covered the confirm button on iPhone.

No payment is taken, so Stars are not needed. If the café later sells gift cards that are used in the café, she will check Telegram's current rules on whether those count as digital goods.

Common mistakes

• Trusting the unsafe user object. Anything in the front-end can be faked. Verify the raw launch data on your server before doing anything that matters.
• Swapping the HMAC key and message. The secret key is derived with "WebAppData" as the key and the bot token as the message.
• Putting the bot token in front-end code. It gives full control of your bot to anyone who reads the page source.
• Delivering purchases on the front-end's word. Deliver only after your bot receives the successful-payment update.
• Selling digital goods outside Stars. Telegram requires Stars for digital goods and services in Mini Apps.
• Ignoring the theme. A hard-coded white app looks broken in dark mode.
• Never calling ready. Telegram keeps showing its loading placeholder until you do.
• Testing only in a desktop browser. The web views inside Telegram behave differently, especially with the keyboard.
• No back button handling. Users get stuck in sub-screens with no way back except closing.

FAQ

Do I need to know how to code to build a Mini App?

To build a custom Mini App, yes: it is a web app with a small backend. Some no-code tools can produce simple ones, and a developer can build the rest. Building the bot side without code is possible with automation tools.

Is hosting a Mini App free?

Telegram does not charge you to run a Mini App, but you host it yourself, so you pay for whatever hosting your app needs. Static apps can run on low-cost or free hosting.

Which programming language should I use?

The front-end is a web page, so HTML, CSS and JavaScript or a framework that produces them. The backend can be any language that can compute HMAC-SHA-256 and call the Bot API.

Can a Mini App get the user's phone number?

Only if the user agrees. The library can ask the user to share their contact, and Telegram shows a confirmation. Without it, you get the user's Telegram ID and name, not their number.

Can I open a Mini App from a channel post?

Yes, with a URL button or a text link using the app's direct t.me link. The dedicated Mini App button type only works in private chats with the bot.

How do I make money from a Mini App?

Sell digital items in Stars, offer subscriptions, show ads where allowed, or support a real-world business. Our guide to making money from a Mini App covers the options and their rules.

Summary

To build a Telegram Mini App, create a bot in @BotFather, build a fast, mobile-first web app on HTTPS hosting, load Telegram's Mini App script, and use Telegram's theme, main button and back button. Register the app as your bot's main Mini App, set the menu button, and create a direct link for posts and ads. Verify every user on your server from the raw launch data with the "WebAppData" HMAC method and an age check, never from the unsafe object. Sell digital goods in Telegram Stars and deliver only after the payment update arrives. Test on Android, iPhone and Desktop in both themes before launch, then promote the app with tracked direct links.