Mini App — размещение приложения
Mini App — это сайт, который открывается внутри Telegram: каталог товаров и корзина, анкета, игра, калькулятор или личный кабинет клиента. Botxona размещает его на HTTPS-адресе, привязывает к кнопке меню бота и раздаёт файлы с кэшированием. Ни сервер, ни домен, ни сертификат настраивать не нужно.
Три способа разместить приложение
1. Загрузить ZIP (самый быстрый)
Откройте бота в панели, перейдите в раздел Mini App и загрузите результат сборки в виде ZIP. В корне архива должен быть index.html — то есть вы архивируете саму папку dist/ (или загружаете исходники проекта — см. ниже). Бот при этом не переразворачивается, приложение поднимается за секунды.
2. Внутри кода бота (обновляется при каждом деплое)
Держите фронтенд в архиве бота:
main.py
requirements.txt
webapp/
index.html
assets/app.js
Папка webapp/ или miniapp/ определяется автоматически. Если имя другое (например dist/), укажите его в botxona.yaml:
webapp:
dir: dist # папка со статикой
mode: static # static | hybrid | proxy
api_prefix: /api # для hybrid/proxy
spa: true # неизвестные пути отдают index.html
Каждый успешный деплой публикует новую версию приложения. Если деплой упал, продолжает работать прежняя версия.
3. Через Telegram
Отправьте @botxona_uz_bot команду /myapps, выберите бота и пришлите ZIP-архив документом. Результат придёт в этот же чат.
Загрузите проект React/Next/Vue как есть
Собирать проект самим не нужно. Заархивируйте исходники проекта (папка с package.json, где есть скрипт build) и загрузите во вкладке Mini App, в чате или держите в папке webapp/ исходников бота. Botxona сама установит пакеты и соберёт проект в изолированной среде, а результат опубликует как обычное статическое приложение. В панели виден живой лог сборки.
- Поддерживается: Vite (React, Vue, Svelte…), Create React App, Next.js, Nuxt, Angular, SvelteKit (с
@sveltejs/adapter-static) и любой проект, у которогоbuildсоздаёт папку сindex.html(out,dist,build,.output/public). - Менеджер пакетов определяется по lock-файлу (
package-lock.json,yarn.lock,pnpm-lock.yaml) или полюpackageManager. Bun не поддерживается — используется npm. Версия Node берётся из.nvmrc/engines.node(18, 20, 22 или 24; по умолчанию 22). - Next.js автоматически переключается на статический экспорт (
output: 'export', картинки без оптимизации) — трогатьnext.configне нужно. - Серверных функций нет. У Mini App нет своего сервера: API routes,
cookies(), Server Actions иforce-dynamicстраницы недоступны. Серверную логику перенесите в бота и вызывайте через префикс/api(режимhybrid). node_modulesне нужен (если положите — будет проигнорирован), архивируйте только исходники. Файлы.envне включаются; значенияVITE_*/NEXT_PUBLIC_*держите в.env.productionили в коде — они всё равно публичны.- Лимиты: архив до 25 МБ (20 МБ при отправке через Telegram), исходники и результат сборки до 60 МБ, до 3000 файлов; сборка — не дольше 10 минут. При ошибке вы получите краткую причину и лог, а предыдущая версия продолжит работать.
Режимы
| Режим | Что происходит | Когда |
|---|---|---|
static | Отдаётся только статика. Приложение открывается даже когда бот спит. | Данные приходят от бота через sendData или сообщения |
hybrid | Статика + запросы с префиксом api_prefix идут в контейнер бота | Приложению нужен свой API (каталог, заказ, профиль) |
proxy | Каждый запрос идёт в контейнер бота | SSR и полностью динамические приложения |
В режимах hybrid и proxy бот должен поднять обычный HTTP-сервер на 0.0.0.0: (TLS не нужен). Спящий бот просыпается на первом запросе — он может занять несколько секунд.
Переменные окружения бота
| Переменная | Значение |
|---|---|
WEBAPP_URL | Полный адрес приложения (без завершающего /) |
WEBAPP_API_PREFIX | Значение api_prefix (/api) |
С их помощью добавьте в бота кнопку, открывающую приложение:
from aiogram.types import KeyboardButton, ReplyKeyboardMarkup, WebAppInfo
import os
kb = ReplyKeyboardMarkup(
keyboard=[[KeyboardButton(text="🛍 Каталог", web_app=WebAppInfo(url=os.environ["WEBAPP_URL"]))]],
resize_keyboard=True,
)
Кнопка меню бота привязывается к приложению автоматически при публикации — это можно отключить в настройках Mini App.
Проверка пользователя (initData)
При открытии приложения Telegram передаёт window.Telegram.WebApp.initData. Проверяйте её в самом боте с помощью BOT_TOKEN — только тогда можно доверять, что запрос пришёл от этого пользователя:
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
Платформа не проверяет и не изменяет initData — она только доставляет запрос вашему боту.
Как правильно собрать файлы
В index.html должен быть подключён telegram-web-app.js, иначе не заработают тема, кнопки и initData:
<script src="https://telegram.org/js/telegram-web-app.js"></script>
Приложение живёт в корне своего адреса, поэтому стандартных настроек Vite/CRA достаточно. Если ваше приложение размещено по пути (адрес в панели выглядит как .../slug), самый надёжный вариант — base: './' в vite.config.js.
Ограничения
- Одно Mini App на одного бота.
- Архив до 25 МБ, в распакованном виде до 60 МБ, до 3000 файлов, один файл до 10 МБ.
- Файлы отдаются как статика: код
.pyили.phpиз архива не выполняется. Динамика работает в самом боте (hybrid/proxy). - Файлы Mini App публичны — не храните в них токены, ключи и пароли.
- На бесплатном тарифе загрузка своих файлов недоступна.
Версии и откат
Каждая загрузка создаёт новую версию. В панели виден список версий — откат выполняется одной кнопкой. Файлы последних 5 версий сохраняются.
Дальше: схема botxona.yaml · Переменные окружения · Логи