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

> A Mini App is a regular web page served over HTTPS that Telegram opens inside the chat. You need a bot from BotFather, a page with the Telegram Web App script, a way to launch it (menu button or link) and server-side verification of user data.

Date: 2026-11-02 · Source: https://oneswitch.ru/en/blog/kak-sozdat-telegram-mini-app-poshagovo/

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:

```html
<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](/blog/proverka-initdata-telegram-mini-app-python/).

## 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](/blog/uvedomleniya-v-telegram-mini-app/)), a catalog with filters ([catalog architecture](/blog/katalog-v-telegram-mini-app-arhitektura/)) 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](/blog/telegram-mini-app-ili-sajt/). Price guidance is in [how much a bot and a Mini App cost](/blog/skolko-stoit-telegram-bot-i-mini-app/).

If you need ready-made development for your task, see the [Telegram bots and Mini Apps](/uslugi/telegram-boty-i-mini-app/) service and the [case studies](/raboty/).

## FAQ

### Do I need to code to build a Mini App?
For a simple page, basic HTML and JavaScript are enough. If you need a database, authentication, notifications and payments, you need a server part, and then it is better to involve a developer.

### How is a Mini App different from a regular bot?
A bot works through messages and buttons, while a Mini App shows a full interface: a catalog, forms, cards and filters. They are often used together: the bot sends notifications and the Mini App shows the data.

### Do I need a separate website for a Mini App?
You need a page served over HTTPS, and it can be part of your website. A Mini App is designed to be opened inside Telegram, so for Google and Yandex search you need a regular site with text content, while the Mini App stays a convenient interface for users.

### Where should I store the bot token?
Only on the server, in environment variables. The token must not appear in the page code or in a repository: whoever gets it can control the bot.