Как создать Telegram Mini App: пошаговая инструкция с кодом (2026)

Telegram Mini App (TWA — Telegram Web App) — это веб-приложение, которое открывается внутри Telegram. Пользователь нажимает кнопку в боте, и вместо перехода на внешний сайт видит полноценное приложение прямо в мессенджере.

Архитектура Telegram Mini App состоит из трёх компонентов:

1. Telegram Bot (точка входа). Бот принимает команды от пользователя и открывает Mini App. Через бота отправляются уведомления, обрабатываются платежи, управляется состояние. Бот — это «дверь» в Mini App.

2. Mini App (фронтенд). Веб-приложение на React, Vue или vanilla JS. Работает в WebView внутри Telegram. Использует Telegram Web App SDK для доступа к функциям Telegram: данные пользователя, HapticFeedback, MainButton, BackButton, тема, цвета.

3. Бэкенд (API-сервер). Серверная часть на Node.js, Python или другом языке. Обрабатывает бизнес-логику, управляет данными, интегрируется с внешними сервисами (платёжные системы, CRM, базы данных).

Как работает Mini App — технический поток: 1. Пользователь открывает бота и нажимает кнопку «Открыть магазин» 2. Бот отправляет ссылку на Mini App (через WebAppInfo или inline keyboard) 3. Telegram открывает WebView с URL Mini App 4. Mini App загружается, получает initData (подписанные данные пользователя) 5. Mini App отправляет initData на бэкенд для верификации 6. Бэкенд проверяет подпись HMAC-SHA256 и возвращает токен сессии 7. Mini App работает с API, используя токен 8. При закрытии Mini App — WebView закрывается, пользователь остаётся в Telegram

Важные технические ограничения: - Mini App работает в WebView (не полноценный браузер) - localStorage и cookies доступны, но могут очищаться - Размер viewport зависит от устройства (мобильный, десктоп) - Telegram SDK доступен только внутри Telegram - Максимальный размер initData — 512 байт

Подробнее о магазине в Mini App и разработке сервисов.

Выбор технологии для Mini App зависит от вашего опыта, сложности проекта и скорости запуска. Вот основные варианты.

1. TWA (Telegram Web App) + React. Самый популярный стек. React обеспечивает компонентный подход, богатую экосистему, быструю разработку. TypeScript добавляет типизацию. Telegram Web App SDK (@twa-dev/sdk или telegram-web-apps) — готовые хуки для React.

2. TWA + Vue.js. Альтернатива React с более простым синтаксисом. Vue 3 + Composition API + TypeScript. Хороший выбор, если команда уже работает с Vue.

3. TWA + Next.js. React-фреймворк с SSR/SSG. Хорош для SEO (если Mini App доступен и вне Telegram). Server Components для оптимизации. Vercel как хостинг.

4. TWA + Vanilla JS. Минимальный размер бандла, максимальная скорость. Без фреймворка. Подходит для простых Mini App (одностраничные формы, калькуляторы).

5. TWA + Svelte. Компилируемый фреймворк. Маленький бандл, высокая производительность. Растущее сообщество.

Мой стек для Mini App: - Фронтенд: React 18 + TypeScript + Vite + Telegram Web App SDK (@twa-dev/sdk) - UI: Tailwind CSS (адаптивный, мобильный-first) - Бэкенд: Node.js + Express/Fastify + TypeScript - База данных: PostgreSQL (Supabase или Railway) - Деплой: Vercel (фронтенд) + Railway (бэкенд) - CMS: Notion API или Google Sheets API

Почему React + TypeScript: - Богатая экосистема компонентов для e-commerce - TypeScript предотвращает ошибки на этапе компиляции - Telegram Web App SDK имеет готовые React-хуки - Легко найти разработчика для поддержки - Hot Module Replacement для быстрой разработки

Почему Vite вместо CRA: - Время сборки: 200-500 мс (vs 10-30 секунд у CRA) - Горячая перезагрузка: мгновенная - Размер бандла: оптимизированный (tree-shaking) - Поддержка TypeScript из коробки

Подробнее о Mini App с оплатой и примерах Mini App.

Первый шаг — создание Telegram-бота, который будет точкой входа для Mini App.

1.1. Создание бота через @BotFather. Откройте Telegram, найдите @BotFather, отправьте /newbot. Укажите имя бота (отображаемое) и username (уникальный, заканчивается на «bot»). Получите токен бота — сохраните его, он понадобится для API.

1.2. Настройка Mini App в BotFather. Отправьте /newapp в BotFather. Выберите бота. Укажите: - Название Mini App - Описание (до 512 символов) - Гифку/видео для превью - URL Mini App (https://your-app.vercel.app)

1.3. Настройка команд бота. Через /setcommands добавьте команды: - /start — приветствие и открытие Mini App - /help — справка - /orders — история заказов

1.4. Настройка кнопки Menu. Через /setmenubutton задайте кнопку меню, которая открывает Mini App. Или используйте WebAppInfo в inline keyboard.

1.5. Настройка домена. Через /setdomain привяжите домен Mini App к боту. Это обязательная мера безопасности — Telegram открывает Mini App только с доверенного домена.

Типичная структура проекта:

 1my-miniapp/
 2├── bot/               # Telegram бот
 3│   ├── index.ts       # Точка входа бота
 4│   ├── commands.ts    # Обработчики команд
 5│   └── payments.ts    # Обработка платежей
 6├── frontend/          # Mini App (React)
 7│   ├── src/
 8│   │   ├── App.tsx
 9│   │   ├── pages/
10│   │   ├── components/
11│   │   └── hooks/
12│   ├── index.html
13│   └── vite.config.ts
14├── backend/           # API-сервер
15│   ├── src/
16│   │   ├── index.ts
17│   │   ├── routes/
18│   │   ├── models/
19│   │   └── services/
20│   └── package.json
21└── README.md

Инициализация проекта (команды в терминале): 1. npm create vite@latest frontend -- --template react-ts 2. cd frontend && npm install @twa-dev/sdk 3. mkdir bot && cd bot && npm init -y && npm install telegraf 4. mkdir ../backend && cd ../backend && npm init -y && npm install express cors

Подробнее о создании бота и магазине в Mini App.

Второй шаг — создание фронтенда Mini App на React с использованием Telegram Web App SDK.

2.1. Установка SDK. В проекте React выполните: npm install @twa-dev/sdk. SDK предоставляет доступ к данным пользователя, теме, HapticFeedback, MainButton, BackButton, платежам.

2.2. Инициализация SDK. В точке входа App.tsx импортируйте SDK и получите объект WebApp. Проверьте, что приложение запущено внутри Telegram (window.Telegram.WebApp). Если нет — покажите заглушку.

2.3. Получение данных пользователя. Telegram передаёт initData — подписанные данные пользователя (ID, имя, язык). Отправляйте initData на бэкенд для верификации подписи. Никогда не доверяйте данным на клиенте.

2.4. Адаптивный дизайн. Mini App работает в мобильном и десктопном Telegram. Используйте CSS Grid или Flexbox. viewport height: используйте var(--tg-viewport-height) вместо 100vh (Telegram может показывать заголовок). Безопасная зона: var(--tg-content-safe-area-inset-top).

2.5. Telegram UI компоненты. Используйте MainButton для главного действия («Добавить в корзину», «Оплатить»). BackButton для навигации назад. HapticFeedback для тактильного отклика (impact, notification, selection).

2.6. Тема и цвета. Telegram передаёт цвета темы (themeParams): bg_color, text_color, hint_color, button_color. Адаптируйте UI под тему пользователя (светлая/тёмная). Используйте CSS-переменные Telegram.

Пример структуры React-компонента Mini App: - App.tsx — инициализация SDK, роутинг, тема - pages/Catalog.tsx — каталог товаров с фильтрами - pages/Product.tsx — карточка товара - pages/Cart.tsx — корзина - pages/Checkout.tsx — оформление заказа - pages/Orders.tsx — история заказов - components/ProductCard.tsx — карточка товара - hooks/useTelegram.ts — хук для Telegram SDK - hooks/useAuth.ts — авторизация через initData

Ключевые правила UI для Mini App: - Крупные элементы (минимум 44×44 px для тапов) - Отступы от краёв экрана (safe area) - Шрифт: system-ui или тот, что передаёт Telegram - Анимации: плавные, не тяжёлые (CSS transitions) - Скролл: native, без кастомных scrollbar

Подробнее о магазине в Mini App и Mini App с оплатой.

Третий шаг — создание серверной части, которая обрабатывает запросы Mini App, управляет данными и интегрируется с внешними сервисами.

3.1. Выбор стека. Для бэкенда Mini App рекомендую: Node.js + Express/Fastify + TypeScript. Альтернативы: Python + FastAPI, Go + Gin. Node.js — оптимальный выбор из-за единого языка с фронтендом.

3.2. Верификация initData. Первый и самый важный endpoint — верификация initData. Telegram подписывает данные пользователя HMAC-SHA256. Бэкенд проверяет подпись и извлекает user_id, first_name, language_code.

3.3. Авторизация. После верификации initData — создайте JWT-токен для сессии. Mini App отправляет токен в заголовке Authorization для всех последующих запросов.

3.4. API endpoints. Типичный набор endpoints для магазина: - GET /api/products — список товаров - GET /api/products/:id — карточка товара - POST /api/cart — добавить в корзину - GET /api/cart — содержимое корзины - POST /api/orders — создать заказ - GET /api/orders — история заказов - POST /api/payments/create — создать платёж - POST /api/webhooks/yukassa — webhook от ЮKassa

3.5. База данных. PostgreSQL — оптимальный выбор для Mini App. Таблицы: users, products, categories, cart_items, orders, order_items, payments. Используйте ORM (Prisma, Drizzle) или raw SQL.

3.6. Кеширование. Кешируйте часто запрашиваемые данные: каталог товаров (Redis, 5 минут), профиль пользователя (Redis, 1 час). Это ускоряет Mini App в 3-5 раз.

3.7. Деплой. Деплой бэкенда: Railway (от 5 $/мес), Render (от 7 $/мес), Vercel Serverless Functions (бесплатно для малых объёмов), VPS (от 300 ₽/мес).

Типичная структура бэкенда:

 1backend/
 2├── src/
 3│   ├── index.ts          # Точка входа Express
 4│   ├── config.ts         # Конфигурация
 5│   ├── middleware/
 6│   │   ├── auth.ts       # Верификация JWT
 7│   │   └── telegram.ts   # Верификация initData
 8│   ├── routes/
 9│   │   ├── products.ts
10│   │   ├── cart.ts
11│   │   ├── orders.ts
12│   │   └── payments.ts
13│   ├── models/
14│   │   ├── user.ts
15│   │   ├── product.ts
16│   │   └── order.ts
17│   └── services/
18│       ├── telegram.ts
19│       ├── yukassa.ts
20│       └── cache.ts
21├── prisma/
22│   └── schema.prisma
23└── package.json

Подробнее о Mini App с оплатой и примерах Mini App.

Четвёртый шаг — интеграция платёжной системы, чтобы принимать оплату прямо в Mini App.

4.1. Telegram Payments (для карточных платежей). Используйте метод sendInvoice Telegram Bot API. Бот отправляет счёт пользователю, Telegram показывает встроенную форму оплаты. После оплаты бот получает успешный_payment callback.

4.2. Telegram Stars (для микроплатежей). Используйте createInvoiceLink с currency "XTR". Минимальный путь до оплаты: 2-3 клика. Идеально для цифровых товаров, подписок, донатов.

4.3. ЮKassa (для российских продаж). Создайте аккаунт в ЮKassa, получите shopId и secretKey. Бэкенд создаёт платёж через API ЮKassa, получает confirmation_url. Mini App открывает confirmation_url в WebView или перенаправляет пользователя.

4.4. Обработка webhook. Для каждого способа оплаты настройте webhook endpoint на бэкенде. Webhook приходит при изменении статуса платежа. Проверяйте подпись, обновляйте статус заказа, уведомляйте пользователя через бота.

Рекомендуемый порядок подключения: 1. Сначала — Telegram Payments (самый простой, встроен в Telegram) 2. Затем — ЮKassa (для полноценного приёма карт и СБП) 3. Потом — Telegram Stars (для микроплатежей и цифровых товаров)

Тестирование оплаты: - Telegram Payments: используйте тестовый токен провайдера - ЮKassa: включите тестовый режим в личном кабинете - Stars: используйте тестовые Stars (BotFather /mybots → Stars)

Подробнее о Mini App с оплатой и магазине в Mini App.

Пятый шаг — тестирование Mini App перед запуском. Это критически важный этап, который определяет качество пользовательского опыта.

5.1. Тестирование в Telegram. Откройте Mini App в Telegram на реальном устройстве (Android и iOS). Проверьте: загрузку, навигацию, оплату, уведомления. WebView на Android и iOS может вести себя по-разному.

5.2. Тестирование на разных устройствах. Проверьте Mini App на: iPhone (SE, 14, 15 Pro), Android (Samsung, Xiaomi, Pixel), планшетах, десктопном Telegram. Размеры экранов отличаются — проверьте адаптивность.

5.3. Тестирование платёжного потока. Пройдите полный цикл: выбор товара → корзина → оформление → оплата → подтверждение. Проверьте: успешную оплату, отклонённую карту, отмену, возврат, повторную попытку.

5.4. Нагрузочное тестирование. Если ожидаете 100+ одновременных пользователей — проведите нагрузочное тестирование API. Инструменты: k6, Artillery, autocannon. Целевое время ответа API: до 200 мс.

5.5. Безопасность. Проверьте: верификацию initData, проверку JWT, защиту от XSS, HTTPS, CORS, rate limiting, SQL injection.

Чек-лист перед запуском: - Mini App загружается за 2 секунды - Все кнопки работают - Оплата проходит успешно - Уведомления приходят - Нет ошибок в консоли - Адаптивный дизайн на всех устройствах - Безопасность проверена - Данные логируются

Подробнее о примерах Mini App и Mini App с оплатой.

Шестой шаг — деплой Mini App на хостинг и запуск для пользователей.

6.1. Деплой фронтенда. Mini App — это обычное веб-приложение. Деплой на Vercel, Netlify, Cloudflare Pages. Настройте CI/CD: push в main → автоматический деплой. Настройте кастомный домен (miniapp.yourdomain.com).

6.2. Деплой бэкенда. API-сервер на Railway, Render или VPS. Настройте переменные окружения: токен бота, ключи ЮKassa, JWT-секрет, URL базы данных. Настройте автоматический деплой из Git.

6.3. Настройка SSL. Telegram требует HTTPS для Mini App. Vercel/Netlify/Railway предоставляют SSL автоматически. Для VPS — Let's Encrypt (бесплатно).

6.4. Привязка домена к боту. Через BotFather /setdomain укажите домен Mini App. Telegram будет открывать Mini App только с этого домена.

6.5. Запуск. Отправьте /start боту. Нажмите кнопку Mini App. Проверьте, что всё работает. Протестируйте на 5-10 реальных пользователях. Соберите обратную связь.

6.6. Мониторинг. Настройте мониторинг: uptime (UptimeRobot), ошибки (Sentry), аналитика (Plausible или Яндекс.Метрика), логи (Railway logs или Grafana).

Оптимизация после запуска: - Кеширование API-ответов (Redis, 5-60 минут) - CDN для статических файлов (Cloudflare) - Lazy loading изображений - Оптимизация бандла (tree-shaking, code splitting) - Service Worker для офлайн-режима (опционально)

Итоговые сроки создания Mini App:

Подробнее о стоимости Mini App и заказе Mini App.

Стоимость разработки Telegram Mini App зависит от сложности функционала, количества интеграций и требований к дизайну. Вот реальные цены.

Простое Mini App — от 80 000 до 150 000 ₽: Одностраничное приложение: форма заявки, калькулятор, каталог без корзины. Без оплаты. Без личного кабинета. Управление данными через Google Sheets. Срок: 10-15 дней.

Среднее Mini App — от 150 000 до 350 000 ₽: Многостраничное приложение: каталог с фильтрами, корзина, оплата (1-2 способа), личный кабинет, история заказов. Админ-панель. Интеграция с ЮKassa. Срок: 21-35 дней.

Сложное Mini App — от 350 000 до 800 000 ₽: Полноценное приложение: каталог до 5 000 SKU, мультивариативность, промокоды, бонусы, 3+ способа оплаты, подписки, интеграция с 1С/CRM, аналитика, A/B-тесты. Срок: 35-60 дней.

Из чего складывается стоимость: - UI/UX дизайн — 15-20% бюджета - Фронтенд разработка — 25-30% - Бэкенд разработка — 25-30% - Интеграции (оплата, CRM, 1С) — 10-15% - Тестирование — 5-10% - Деплой и настройка — 3-5%

Сравнение с альтернативами:

Стоимость фрилансера vs агентства:

Подробнее о заказе Mini App и магазине в Mini App.

Разработка Telegram Mini App — это не просто «сделать сайт в WebView». Вот 8 ошибок, которые допускают разработчики, и как их избежать.

Ошибка 1: Игнорирование initData. Разработчик не верифицирует initData и доверяет данным на клиенте. Мошенник подделывает user_id и получает чужие данные. Решение: всегда проверять HMAC-SHA256 подпись на сервере.

Ошибка 2: Использование 100vh. CSS-свойство 100vh не учитывает заголовок Telegram и safe area. Mini App обрезается снизу. Решение: используйте var(--tg-viewport-height) или var(--tg-viewport-stable-height).

Ошибка 3: Тяжёлый бандл. Мега-бандл (1 MB+) грузится 5+ секунд в WebView. Пользователь закрывает. Решение: code splitting, lazy loading, оптимизация изображений. Целевой размер: до 200 KB gzip.

Ошибка 4: Нет офлайн-режима. Нет интернета — Mini App показывает белый экран. Решение: graceful degradation, кеш в localStorage, fallback UI.

Ошибка 5: Кастомный скролл. Разработчик делает кастомный скроллбар, который конфликтует с нативным скроллом Telegram. Решение: используйте нативный скролл, overflow-y: auto.

Ошибка 6: Нет HapticFeedback. Пользователь тапает кнопку — нет тактильного отклика. Mini App «не живой». Решение: добавьте HapticFeedback при действиях (добавление в корзину, оплата, ошибка).

Ошибка 7: Нет обработки темы. Mini App не адаптируется под тёмную/светлую тему Telegram. В тёмной теме — чёрный текст на чёрном фоне. Решение: используйте themeParams из Telegram SDK.

Ошибка 8: Деплой на HTTP. Telegram требует HTTPS. HTTP-ссылка не откроется в Telegram. Решение: всегда используйте SSL. Vercel/Netlify/Railway предоставляют SSL автоматически.

Главный принцип: Mini App — это не обычный сайт. Это приложение внутри Telegram. Используйте Telegram SDK на максимум: тема, haptic, MainButton, initData. Игнорирование SDK = плохой UX.

Подробнее о Mini App под ключ и примерах Mini App.

Создание Telegram Mini App — это чёткий процесс из 6 шагов. От создания бота до запуска рабочего приложения — 2-6 недель и 80 000-800 000 ₽ в зависимости от сложности.

Краткое резюме 6 шагов:

Три причины создать Mini App прямо сейчас:

1. Низкий порог входа. От 80 000 ₽ и 10 дней — полноценное приложение. Мобильное приложение стоит от 500 000 ₽ и 3 месяца.

2. Аудитория Telegram. 900 млн пользователей без привлечения трафика. Органический рост через Telegram-каналы и ботов.

3. Быстрая итерация. Обновления деплоятся за секунды (без App Store/Google Play). A/B-тесты в реальном времени. Быстрый фидбек от пользователей.

Если вы хотите узнать больше, читайте магазин в Mini App, Mini App с оплатой и примеры Mini App.