Botxona

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 whose build produces a folder with index.html (out, dist, build, .output/public).
  • Package manager is taken from the lock file (package-lock.json, yarn.lock, pnpm-lock.yaml) or the packageManager field. 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 touch next.config.
  • No server features. A Mini App has no server of its own: API routes, cookies(), Server Actions or force-dynamic pages are not available. Move server logic into your bot and call it through the /api prefix (hybrid mode).
  • node_modules is not needed (it is ignored if you include it) — zip the source only. .env files are never included; values for VITE_* / NEXT_PUBLIC_* must live in .env.production or 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

ModeWhat happensWhen to use
staticStatic files only. The app opens even while the bot sleeps.Data flows through the bot via sendData or messages
hybridStatic files + requests under api_prefix go to the bot containerThe app needs its own API (catalog, order, profile)
proxyEvery request goes to the bot containerSSR 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

VariableValue
WEBAPP_URLThe app's full URL (no trailing /)
WEBAPP_API_PREFIXThe 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: .py or .php code 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