Botxona

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 · Переменные окружения · Логи