How to build a Telegram Mini App: a step-by-step guide

A Telegram Mini App is a web application that opens inside Telegram without switching to a browser. Technically it is an ordinary page built with HTML, CSS and JavaScript. Below are the steps to launch a first version.

Step 1. Create a bot

A Mini App is always tied to a bot. In Telegram open @BotFather, send the /newbot command and choose a name and a username (it ends with bot). BotFather gives you the bot token. Keep the token on the server only and never put it in the page code.

Step 2. Prepare the page

Telegram opens the address you provide, so the page has to be hosted somewhere. The main requirement is that the address works over HTTPS. A regular hosting plan, a VPS or static hosting will do. A single index.html is enough for a first version.

Step 3. Connect Telegram Web App

Add the Telegram script to <head> and use the Telegram.WebApp object:

<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
  const tg = window.Telegram.WebApp;
  tg.ready();    // tell Telegram the page has loaded
  tg.expand();   // expand the window to full height
  document.getElementById('hello').textContent =
    'Hello, ' + (tg.initDataUnsafe.user?.first_name || 'guest');
</script>

Useful things to know at the start:

• tg.themeParams returns the Telegram theme colors, so you can match the light and dark themes.
• tg.MainButton is the large button at the bottom of the window for the main action, for example “Send request”.
• tg.BackButton is the “back” button in the window header.

Step 4. Link the Mini App to the bot

There are several ways to open a Mini App:

1. The bot menu button. It is set in the bot settings through @BotFather: you provide the page address and the button appears next to the input field.
2. A button in a message. The bot sends an inline button or a keyboard button of type web_app with the page address.
3. A direct link. The /newapp command in @BotFather registers a Mini App and gives you a link like t.me/your_bot/name. You can place it on your site or in a channel, or turn it into a QR code.

Step 5. Verify the user on the server

The data in initDataUnsafe comes from the client, so it cannot be trusted: a user can forge a request. If the Mini App writes data or shows personal information, send the tg.initData string to your server and verify its signature with the bot token. A Python example is in the article verifying initData in a Telegram Mini App.

Step 6. Test on real devices

Open the Mini App in Telegram on a phone and on a computer. Check:

• the light and dark themes;
• a small screen and a keyboard that covers input fields;
• that the page does not break on a slow connection;
• how the “back” button behaves.

What to add next

After the first version you usually need user notifications (how to set them up), a catalog with filters (catalog architecture) and a link to your website, which stays for search. If you are choosing between a site and a Mini App, see Mini App or a website. Price guidance is in how much a bot and a Mini App cost.

If you need ready-made development for your task, see the Telegram bots and Mini Apps service and the case studies.