gramdocs.tech
Документация

Деплой mini-app: хостинг и HTTPS-требования

Выложишь Mini App на HTTPS-хостинг, проверишь заголовки и подключишь URL в BotFather.

HTTPS обязателен

Telegram открывает Mini App только по HTTPS с валидным сертификатом. http://, самоподписанный сертификат в проде и «открыть HTML с диска» — не рабочие варианты для пользователей. Для локальной разработки используют HTTPS-туннель к localhost.

Хостинг — любой static/SSR: Vercel, Cloudflare Pages, Netlify, свой nginx + Let's Encrypt.

Статика на Vercel + проверка

Пример минимального package.json и деплоя статики (Vite):

bash
# Node.js 20+, vite ^6
npm create vite@latest my-mini-app -- --template vanilla-ts
cd my-mini-app
npm install

index.html должен подключать официальный скрипт:

html
<!DOCTYPE html>
<html lang="ru">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, viewport-fit=cover"
    />
    <script src="https://telegram.org/js/telegram-web-app.js"></script>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Деплой и привязка URL:

bash
npm run build
npx vercel --prod
# → https://my-mini-app.vercel.app

Локальный HTTPS-туннель для отладки в Telegram:

bash
# cloudflared (пример) или ngrok
cloudflared tunnel --url http://127.0.0.1:5173
# → https://xxxx.trycloudflare.com  ← этот URL в BotFather / Menu Button

Проверка после выкладки:

typescript
// Быстрый smoke-check с машины разработчика
async function assertHttpsApp(url: string): Promise<void> {
  if (!url.startsWith("https://")) {
    throw new Error("URL должен быть https://");
  }

  const res = await fetch(url, { redirect: "follow" });
  if (!res.ok) {
    throw new Error(`HTTP ${res.status} для ${url}`);
  }

  const html = await res.text();
  if (!html.includes("telegram-web-app.js")) {
    throw new Error("В HTML нет telegram-web-app.js");
  }
}

await assertHttpsApp("https://my-mini-app.vercel.app/");

CORS: если фронт на app.example.com, а API на api.example.com, разреши origin фронта на бэкенде. Запросы с initData идут с твоего домена Mini App.

Как это работает

  • Telegram WebView загружает URL как обычный браузер, но требует HTTPS.
  • Сертификат должен доверяться системой (Let's Encrypt / хостинг).
  • Туннель временно даёт публичный HTTPS → твой localhost для тестов Menu Button.
  • Кэш CDN — после деплоя иногда нужна жёсткая перезагрузка; для telegram-web-app.js лучше официальный URL Telegram, не копия у себя.

Частые ошибки

В BotFather оставил http:// или старый preview-URL → пользователь видит ошибку загрузки. После каждого смены домена обнови Menu Button / /newapp.

SPA без fallback на index.html → прямые пути /settings отдают 404 на хостинге. Настрой rewrite на index.html.

API по HTTP Mixed Content → страница HTTPS не вызовет http://api.... API тоже только HTTPS.

Что дальше

Материалы gramdocs.tech носят образовательный характер и не являются финансовой, юридической или инвестиционной рекомендацией. Работа с блокчейном TON и токеном Gram связана с рисками потери средств. Правовая информация