Bots
Where to host a Telegram Mini App: hosting for apps inside Telegram
In short
You can host a Telegram Mini App on any host that serves a page over HTTPS, because Telegram simply opens that link inside the chat. The interface itself is an ordinary website built with React, Vue or plain HTML, and next to it there is usually a backend for data and a bot that shows the launch button. On Netrun all three parts can be published as one project or separately, and you get a ready HTTPS link for BotFather. User data coming from Telegram has to be validated on the server, never trusted in the browser.
- A Telegram Mini App is a web page that Telegram opens inside the chat from an HTTPS link.
- A Mini App is registered in BotFather with the /newapp command or attached to the bot menu button with /setmenubutton.
- User data reaches the Mini App as an initData string, and its signature is checked on the server with HMAC-SHA-256 using a key derived from the bot token.
- The initDataUnsafe field can be forged in the browser, so the server must never make decisions based on it.
- The bot token must never be put into frontend code, because anything that runs in the browser can be read by any user.
A Mini App looks like part of Telegram, but it is simpler than it seems: it is a regular web page that Telegram opens in its own window on top of the chat. So you host it like a website, on a service that gives you an HTTPS address. Telegram has no separate app store and no special server for Mini Apps: you hand over a link and Telegram opens it.
The tricky part is that a Mini App is rarely a single page. Almost always it needs a backend that stores data and checks that a request really comes from a Telegram user, plus a bot through which people find the app in the first place. Below is how to split these parts, where to keep them and what to do in BotFather so the button opens your app. If the frontend and backend live on different addresses, read the guide on CORS errors first.
| Part | What it is | Where it lives |
|---|---|---|
| Frontend | A page built with React, Vue, Svelte or plain HTML that Telegram opens inside the chat | Any website host with HTTPS: a built folder of files or a web app |
| Backend | Handles requests from the frontend, validates initData, stores orders, scores and settings | An always-running web app: FastAPI, Flask, Express, Go and so on |
| Bot | Replies in the chat, sends the launch button, delivers notifications | A separate running program, or part of the same backend if the bot uses a webhook |
| HTTPS address | The link you give to BotFather | Provided by the host; Telegram will not accept a link without HTTPS |
| Data | Users, purchases, game progress | A database: SQLite in a persistent folder or PostgreSQL as a separate service |
| Keys | Bot token, payment and third-party API keys | Only on the server, in environment variables, never in frontend code |
Build the frontend and test it in a regular browser#
A Mini App is a website, so first make sure it opens as one. Build your React or Vue project with the usual build command and include the telegram-web-app.js script on the page, which is how the app gets user data, the color theme and Telegram buttons. Open the built version in a browser: a white screen at this stage almost always means wrong file paths or a crash in the code, and it will not go away inside Telegram.
Decide how many parts your app has#
If the Mini App only displays information, the frontend alone is enough. If there are orders, scores, payments or personal data, you need a backend. A convenient setup is a backend that serves the built frontend and answers API calls on the same address, which avoids CORS errors altogether. The frontend, backend and bot can be described in docker-compose and published as one project, or split into separate projects.
Validate initData on the server#
When a user opens the Mini App, Telegram passes it an initData string with user data and a signature. The frontend should send that string to your backend, and the backend should verify the signature as described in the Telegram docs: the key is derived from the bot token, the comparison uses HMAC-SHA-256, and the auth_date field tells you how fresh the data is. Many bot libraries ship this check ready-made. The initDataUnsafe field is fine for showing a name in the UI, but anyone can fake it.
Keep the bot token out of frontend code#
Code that runs in the browser can be opened and read by any user, so the bot token and payment keys must live only on the server. Read them from environment variables and set the values in your hosting settings. On Netrun this is the Secrets tab: values are stored encrypted and passed to the project as environment variables.
Publish the project and get an HTTPS address#
The backend must listen on 0.0.0.0 and on the port from the PORT environment variable, otherwise it is not reachable from outside. A built frontend without a backend is published as a static site. On Netrun you upload the code as an archive, a folder or from GitHub, the language and start command are detected automatically, and you get an HTTPS link you can hand to Telegram right away.
Connect the address in BotFather#
There are two main routes. The /newapp command creates a Mini App with its own link like t.me/your_bot/your_app, which is handy to share in channels and ads. The /setmenubutton command adds a button next to the message field in the chat with your bot that opens your address. On top of that, the bot can send a launch button right in a message, which is done in code.
A Mini App does not need special hosting, just ordinary hosting with HTTPS and room for a backend and a bot. On Netrun the frontend, backend and bot are published from code with no server setup, the HTTPS link is issued right away and tokens are kept in secrets. To be honest about the free plan: a site there sleeps when nobody visits and wakes up when opened, so the first launch after a pause takes a few seconds, and a bot runs only for a limited time. If people open your Mini App every day and the bot has to reply around the clock, go with Pro. Try Netrun.
Common questions
Can I host a Telegram Mini App on GitHub Pages?
The frontend, yes: GitHub Pages serves static pages over HTTPS and Telegram will open that link. But the backend and the bot cannot run there, because GitHub Pages does not run programs. If the app has to store data, verify users or take payments, the backend still has to live somewhere else.
Why does my Mini App open as a blank white screen?
Most often the file paths are wrong: after the build the page looks for scripts where they are not. The second common cause is a crash on startup, or a request to the backend over http instead of https. Open the same link in a normal browser and check the errors in the developer console.
Do I need my own domain for a Mini App?
No. Telegram requires an HTTPS address, not a custom domain, so the link your host gives you is enough. A custom domain is only needed if you want a nicer address or already use it for a website. On Netrun custom domains are available on the Pro plan.
Can the frontend, backend and bot live in one project?
Yes. The simplest setup is a backend that serves the built frontend and the app API, with the bot running on a webhook inside the same backend. If there are more parts, describe them in docker-compose, and the memory and CPU of the plan are then shared between the services.
Why should I not trust initDataUnsafe?
Because it is just data in the browser, and anyone with basic skills can put any name and any user ID there. The only thing you can trust is the initData string whose signature your server has checked with the bot token. Anything involving money, bonuses or access should be decided only on verified data.
Can I host a Telegram bot?
Yes. Upload the bot code and provide the token from BotFather (Telegram itself gives it to you when you create the bot) — Netrun starts the bot, and no VPS or manual setup is needed. On the free plan the bot runs for 3 hours so you can check everything; to keep it running around the clock, switch to the Pro plan.
Can I run several services at once?
Yes. With docker-compose one project can bring up a whole set of services — an app together with a database, a cache and a background worker, say. We do not cap how many: the real ceiling is the memory and CPU of your plan, which are shared between the services of the project.
How do I put a website online?
Upload your site code as a ZIP archive or from GitHub — Netrun builds it and gives you a working link with HTTPS. A static site (HTML, CSS, JS), a React app or a Python site all work. There is no domain to buy and no server or certificates to set up.