Mini App — hosting your app
A Mini App is a site that opens inside Telegram: a product catalog with a cart, a form, a game, a calculator or a customer's personal area. Botxona hosts it on an HTTPS URL, wires it to your bot's menu button and serves the files with caching. No server, domain or certificate to set up.
Three ways to publish
1. Upload a ZIP (fastest)
Open the bot in the dashboard, go to the Mini App tab and upload your build output as a ZIP. index.html must sit at the root of the archive — that is, you zip the dist/ folder itself (or upload the project source — see below). The bot is not redeployed; the app is live in seconds.
2. Inside the bot source (updates on every deploy)
Keep the frontend in the bot's own archive:
main.py
requirements.txt
webapp/
index.html
assets/app.js
A webapp/ or miniapp/ folder is detected automatically. For any other name (say dist/), declare it in botxona.yaml:
webapp:
dir: dist # the static files folder
mode: static # static | hybrid | proxy
api_prefix: /api # for hybrid/proxy
spa: true # unknown paths serve index.html
Every successful deploy publishes a new release of the app. If a deploy fails, the previous release keeps serving.
3. From Telegram
Send /myapps to @botxona_uz_bot, pick the bot and drop the ZIP as a document. The result arrives in the same chat.
Upload your React/Next/Vue project as-is
You do not have to run the build yourself. Zip the project source (the folder with package.json that has a build script) and upload it on the Mini App tab, in the chat, or keep it in webapp/ of the bot source. Botxona installs the packages and builds the project in an isolated environment, then publishes the result like an ordinary static app. The dashboard shows a live build log.
- Supported: Vite (React, Vue, Svelte…), Create React App, Next.js, Nuxt, Angular, SvelteKit (with
@sveltejs/adapter-static) and any project whosebuildproduces a folder withindex.html(out,dist,build,.output/public). - Package manager is taken from the lock file (
package-lock.json,yarn.lock,pnpm-lock.yaml) or thepackageManagerfield. Bun is not supported — npm is used instead. The Node version comes from.nvmrc/engines.node(18, 20, 22 or 24; default 22). - Next.js is switched to a static export automatically (
output: 'export', unoptimized images) — you do not need to touchnext.config. - No server features. A Mini App has no server of its own: API routes,
cookies(), Server Actions orforce-dynamicpages are not available. Move server logic into your bot and call it through the/apiprefix (hybridmode). node_modulesis not needed (it is ignored if you include it) — zip the source only..envfiles are never included; values forVITE_*/NEXT_PUBLIC_*must live in.env.productionor the code, and they are public anyway.- Limits: the archive up to 25 MB (20 MB when sent through Telegram), the source and the build result up to 60 MB, 3000 files; a build may take at most 10 minutes. If a build fails, you get a short reason and the log; the previous version stays live.
Modes
| Mode | What happens | When to use |
|---|---|---|
static | Static files only. The app opens even while the bot sleeps. | Data flows through the bot via sendData or messages |
hybrid | Static files + requests under api_prefix go to the bot container | The app needs its own API (catalog, order, profile) |
proxy | Every request goes to the bot container | SSR and fully dynamic apps |
In hybrid and proxy your bot must open a plain HTTP server on 0.0.0.0: (no TLS needed). A sleeping bot is woken by the request — the first one may take a few seconds.
Environment variables in the container
| Variable | Value |
|---|---|
WEBAPP_URL | The app's full URL (no trailing /) |
WEBAPP_API_PREFIX | The api_prefix value (/api) |
Use them to add a button that opens the app:
from aiogram.types import KeyboardButton, ReplyKeyboardMarkup, WebAppInfo
import os
kb = ReplyKeyboardMarkup(
keyboard=[[KeyboardButton(text="🛍 Catalog", web_app=WebAppInfo(url=os.environ["WEBAPP_URL"]))]],
resize_keyboard=True,
)
The bot's chat menu button is pointed at the app automatically when it goes live; you can switch that off in the Mini App settings.
Verifying the user (initData)
When the app opens, Telegram provides window.Telegram.WebApp.initData. Verify it inside your bot with BOT_TOKEN — only then can you trust that a request really comes from that user:
import hashlib, hmac, os
from urllib.parse import parse_qsl
def verify_init_data(init_data: str) -> dict | None:
pairs = dict(parse_qsl(init_data, strict_parsing=True))
got = pairs.pop("hash", "")
check = "\n".join(f"{k}={pairs[k]}" for k in sorted(pairs))
secret = hmac.new(b"WebAppData", os.environ["BOT_TOKEN"].encode(), hashlib.sha256).digest()
want = hmac.new(secret, check.encode(), hashlib.sha256).hexdigest()
return pairs if hmac.compare_digest(got, want) else None
The platform never validates or rewrites initData — it only delivers the request to your bot.
Building the files correctly
index.html must load telegram-web-app.js, otherwise the theme, buttons and initData will not work:
<script src="https://telegram.org/js/telegram-web-app.js"></script>
Your app lives at the root of its own URL, so the default Vite/CRA settings are enough. If your app is hosted under a path (the dashboard shows an address like .../slug), the most robust option is base: './' in vite.config.js.
Limits
- One Mini App per bot.
- Archive up to 25 MB, up to 60 MB unpacked, up to 3000 files, 10 MB per file.
- Files are served statically:
.pyor.phpcode in the archive is never executed. Dynamic parts run in the bot itself (hybrid/proxy). - Mini App files are public — never put tokens, keys or passwords in them.
- Uploading your own files is not available on the free plan.
Releases and rollback
Every upload creates a release. The dashboard lists them and rolls back with a single button. The files of the last 5 releases are kept.
Next: the botxona.yaml schema · Environment variables · Logs