Как создать Telegram Mini App: полная инструкция для разработчика

Telegram Mini App — это полноценное веб-приложение, которое работает прямо внутри мессенджера. Без установки, без App Store, без ожидания модерации. Пользователь нажимает кнопку — и перед ним интерфейс: магазин, сервис бронирования, игра, что угодно.

Звучит просто, но на практике разработчики натыкаются на десятки нюансов: какой SDK выбрать, как получить данные пользователя, как всё это протестировать без публикации. В этой статье разберём весь процесс от нуля до рабочего Mini App — без воды, с конкретными шагами.

Если вы ещё не определились, нужен ли вам Mini App или хватит обычного бота, — почитайте нашу статью о задачах, которые решает Telegram-бот. А общий обзор возможностей платформы мы разобрали в материале о будущем Telegram Mini Apps.

Что потребуется для старта

Прежде чем писать код, подготовьте рабочее окружение:

Node.js 18+ и менеджер пакетов (npm, pnpm или yarn)
HTTPS-домен — Telegram загружает Mini App только по HTTPS. На этапе разработки подойдёт туннель через ngrok или Cloudflare Tunnel
Telegram-аккаунт — очевидно, но на нём не должно быть ограничений
Бот в BotFather — Mini App всегда привязан к боту

Со стеком фронтенда ограничений нет: React, Vue, Svelte, vanilla JS — Telegram всё равно, это просто WebView. Но самая развитая экосистема SDK сейчас — под React, поэтому в примерах будем использовать именно его.

Шаг 1: Регистрация Mini App в BotFather

Откройте @BotFather и выполните последовательность команд:

/newbot — создайте бота (если его ещё нет). Сохраните токен
/mybots → выберите бота → Bot Settings → Menu Button → задайте URL вашего будущего приложения
Или используйте /newapp — это создаст Mini App, привязанный к боту

BotFather попросит указать URL. На этапе разработки вставьте адрес ngrok-туннеля — потом замените на продакшен-домен.

Совет: создайте отдельного бота для разработки. Менять URL в BotFather каждый раз неудобно, а два бота (dev и prod) решают проблему.

Шаг 2: Выбор SDK

Telegram предоставляет низкоуровневый Web App API через глобальный объект window.Telegram.WebApp. Полное описание всех методов и событий — в официальной документации Telegram. Работать с API напрямую можно, но неудобно: нет типизации, нет реактивности, много бойлерплейта.

Поэтому для серьёзной разработки берите один из SDK:

@telegram-apps/sdk — универсальный

Фреймворк-агностичный пакет. Подходит для любого стека: vanilla JS, Vue, Svelte. Предоставляет типизированные обёртки над всеми методами Telegram Web App API.

npm install @telegram-apps/sdk

@telegram-apps/sdk-react — для React-проектов

Если вы делаете telegram mini app на React (а это самый частый выбор), ставьте React-обёртку. Пакет @telegram-apps/sdk-react даёт готовые хуки: useInitData, useMainButton, useBackButton, useHapticFeedback и другие.

npm install @telegram-apps/sdk-react

import { useInitData, useMainButton } from '@telegram-apps/sdk-react';

function OrderPage() {
  const initData = useInitData();
  const mainButton = useMainButton();

  // Данные пользователя доступны сразу
  const user = initData?.user;

  const handleOrder = () => {
    mainButton.setText('Оформить заказ');
    mainButton.show();
    mainButton.on('click', () => {
      // отправляем заказ на бэкенд
    });
  };

  return (
    <div>
      <h1>Привет, {user?.firstName}!</h1>
      <button onClick={handleOrder}>Выбрать</button>
    </div>
  );
}

Оба пакета поддерживают TypeScript из коробки. Если вы использовали старую библиотеку @twa-dev/sdk — переходите на @telegram-apps/sdk-react, она актуальнее и активно поддерживается.

Подробный пошаговый туториал с настройкой Vite, роутинга и компонентов — в нашей статье «Создаём Telegram Mini App на React».

Шаг 3: Инициализация и данные пользователя

При запуске Mini App Telegram передаёт в WebView параметры: кто открыл приложение, из какого чата, на каком языке. Эти данные доступны через initDataUnsafe.

Что внутри initDataUnsafe

import { retrieveLaunchParams } from '@telegram-apps/sdk';

const { initDataRaw, initData } = retrieveLaunchParams();

// initData.user содержит:
// - id: number          — Telegram ID пользователя
// - firstName: string   — имя
// - lastName?: string   — фамилия
// - username?: string   — @username
// - languageCode?: string — язык (ru, en, ...)
// - isPremium?: boolean — Telegram Premium

Объект initDataUnsafe называется «unsafe» не случайно — на клиенте этим данным нельзя доверять. Пользователь может подменить их через DevTools. Поэтому критически важно валидировать initDataRaw на бэкенде.

Валидация на сервере

Telegram подписывает initDataRaw HMAC-ключом, который генерируется из токена вашего бота. Алгоритм проверки:

import hmac
import hashlib
from urllib.parse import parse_qs

def validate_init_data(init_data_raw: str, bot_token: str) -> bool:
    parsed = parse_qs(init_data_raw)
    received_hash = parsed.get("hash", [""])[0]

    # Собираем строку для проверки
    data_pairs = []
    for key, values in sorted(parsed.items()):
        if key == "hash":
            continue
        data_pairs.append(f"{key}={values[0]}")
    data_check_string = "\n".join(data_pairs)

    # Генерируем ключ из токена бота
    secret_key = hmac.new(
        b"WebAppData", bot_token.encode(), hashlib.sha256
    ).digest()

    # Считаем HMAC
    computed_hash = hmac.new(
        secret_key, data_check_string.encode(), hashlib.sha256
    ).hexdigest()

    return computed_hash == received_hash

Никогда не пропускайте этот шаг. Без валидации любой пользователь может представиться кем угодно.

Шаг 4: Архитектура Mini App

Типичная архитектура Telegram Mini App выглядит так:

┌──────────────────────┐
│  Telegram WebView     │
│  (React/Vue/Svelte)   │
│  + @telegram-apps/sdk │
└──────────┬───────────┘
           │ HTTPS
┌──────────▼───────────┐
│  Ваш бэкенд          │
│  (FastAPI / Express)  │
│  - валидация initData │
│  - бизнес-логика      │
│  - Telegram Bot API   │
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│  БД + внешние API     │
└───────────────────────┘

Что на фронте, что на бэке

Фронтенд отвечает за UI и взаимодействие с Telegram SDK: кнопки, хаптик-фидбек, тема, навигация. Никакой бизнес-логики и секретов.

Бэкенд — валидация данных, обработка заказов, платежей, работа с Telegram Bot API (отправка уведомлений, обновление сообщений).

Фронтенд деплоится как статика (Vercel, Netlify, свой VDS), бэкенд — как обычный API-сервер.

Шаг 5: Работа с UI-компонентами Telegram

Telegram предоставляет нативные UI-элементы, которые выглядят как часть мессенджера. Используйте их — пользователи ожидают привычный интерфейс.

MainButton — главная кнопка

Большая кнопка внизу экрана. Используется как основной CTA: «Оформить заказ», «Оплатить», «Подтвердить».

import { useMainButton } from '@telegram-apps/sdk-react';

function Checkout({ total }: { total: number }) {
  const mainButton = useMainButton();

  useEffect(() => {
    mainButton.setText(`Оплатить ${total} ₽`);
    mainButton.show();
    mainButton.on('click', handlePayment);

    return () => {
      mainButton.hide();
      mainButton.off('click', handlePayment);
    };
  }, [total]);

  return <CartItems />;
}

BackButton — кнопка «Назад»

Появляется в заголовке WebView. Обязательно включайте на вложенных экранах — без неё пользователь застрянет.

import { useBackButton } from '@telegram-apps/sdk-react';
import { useNavigate } from 'react-router-dom';

function ProductPage() {
  const backButton = useBackButton();
  const navigate = useNavigate();

  useEffect(() => {
    backButton.show();
    backButton.on('click', () => navigate(-1));
    return () => backButton.hide();
  }, []);

  return <ProductDetails />;
}

HapticFeedback — вибрация

Мелочь, которая делает приложение «живым». Используйте при нажатиях, успешных действиях, ошибках.

import { useHapticFeedback } from '@telegram-apps/sdk-react';

function LikeButton() {
  const haptic = useHapticFeedback();

  return (
    <button onClick={() => {
      haptic.impactOccurred('medium');
      toggleLike();
    }}>
      ❤️
    </button>
  );
}

Шаг 6: Адаптация под тему Telegram

У Telegram есть светлая и тёмная тема, и ваш Mini App должен подстраиваться. SDK даёт доступ к цветам текущей темы:

import { useThemeParams } from '@telegram-apps/sdk-react';

function App() {
  const theme = useThemeParams();

  return (
    <div style={{
      backgroundColor: theme.bgColor,
      color: theme.textColor,
    }}>
      <h1 style={{ color: theme.headerBgColor }}>
        Каталог
      </h1>
    </div>
  );
}

Если используете Tailwind CSS, проще всего пробросить переменные темы в CSS custom properties и использовать их в утилитарных классах. Подробнее о работе с Tailwind — в нашем гайде по адаптивному дизайну.

Шаг 7: Тестирование и отладка

Главная боль разработки Mini App — тестирование. Приложение работает внутри Telegram WebView, и обычные Chrome DevTools недоступны.

Способы отладки

1. Telegram Desktop + DevTools

В десктопном клиенте Telegram есть скрытая функция: кликните правой кнопкой по Mini App и выберите «Inspect Element». Откроются полноценные DevTools.

Для включения на macOS: запустите Telegram Desktop, быстро кликните 5 раз по иконке Settings — появится меню отладки.

2. Eruda — встроенная консоль

Для мобильного тестирования вставьте Eruda — это мобильный DevTools:

<script src="https://cdn.jsdelivr.net/npm/eruda"></script>
<script>eruda.init();</script>

Уберите перед продакшеном — но на этапе разработки это спасение.

3. Бот-тестировщик

Создайте тестового бота через BotFather с URL, который указывает на ваш локальный туннель (ngrok). Меняете код → обновляете страницу в Telegram → видите результат.

Частые грабли при тестировании

CORS — бэкенд должен разрешать запросы с домена Telegram (https://web.telegram.org)
Кеширование — Telegram агрессивно кеширует WebView. Добавляйте ?v=hash к URL ресурсов или настройте правильные заголовки Cache-Control
Разные платформы — WebView на iOS, Android и Desktop ведут себя по-разному. Тестируйте на всех трёх

Чтобы не повторять типичные ошибки при разработке под Telegram, загляните в подборку 10 распространённых проблем — многие из них актуальны и для Mini App.

Шаг 8: Деплой и публикация

Когда всё работает локально, пора выкатывать в продакшен.

Фронтенд

Mini App — это статический сайт. Соберите его и разместите на любом хостинге с HTTPS:

npm run build

Результат сборки (папка dist или out) заливаете на сервер. На VDS — через nginx, на облаке — Vercel, Netlify, Cloudflare Pages.

Обновите URL в BotFather

Замените ngrok-адрес на продакшен-домен:

/mybots → выберите бота → Bot Settings → Menu Button → новый URL

Добавьте в Telegram Directory

Если хотите, чтобы ваш Mini App находили через поиск в Telegram, отправьте заявку через @BotFather командой /myapps → выберите приложение → Submit for Review.

Telegram Mini App vs VK Mini Apps

Если вы работаете на российском рынке, логичный вопрос — а может, VK Mini Apps? Кратко:

Аудитория: Telegram растёт быстрее, но VK по-прежнему силён в регионах
Монетизация: Telegram Payments проще в интеграции, VK Pay требует отдельной заявки
DX: у Telegram лучше SDK и документация, VK Mini Apps используют свой VKUI-фреймворк
Платформа: если уже есть Telegram-бот, Mini App — логичное расширение

Подробное сравнение с таблицами и рекомендациями — в статье VK Mini Apps vs Telegram Mini Apps.

Чеклист перед запуском

Пройдитесь по этому списку перед тем, как показать Mini App пользователям:

Что дальше

Telegram Mini App — это не просто «сайт в мессенджере». Это канал с нулевым порогом входа для пользователя: не надо ничего скачивать, регистрироваться, вводить данные. Всё уже есть в Telegram.

Если вы только начинаете — пошаговый React-туториал проведёт вас через создание первого приложения за пару часов. А если нужен Mini App для бизнеса — обращайтесь, разработаем под ключ.

Что потребуется для старта

Прежде чем писать код, подготовьте рабочее окружение:

Node.js 18+ и менеджер пакетов (npm, pnpm или yarn)
HTTPS-домен — Telegram загружает Mini App только по HTTPS. На этапе разработки подойдёт туннель через ngrok или Cloudflare Tunnel
Telegram-аккаунт — очевидно, но на нём не должно быть ограничений
Бот в BotFather — Mini App всегда привязан к боту

Шаг 1: Регистрация Mini App в BotFather

Откройте @BotFather и выполните последовательность команд:

/newbot — создайте бота (если его ещё нет). Сохраните токен
/mybots → выберите бота → Bot Settings → Menu Button → задайте URL вашего будущего приложения
Или используйте /newapp — это создаст Mini App, привязанный к боту

Совет: создайте отдельного бота для разработки. Менять URL в BotFather каждый раз неудобно, а два бота (dev и prod) решают проблему.

Шаг 2: Выбор SDK

Поэтому для серьёзной разработки берите один из SDK:

@telegram-apps/sdk — универсальный

npm install @telegram-apps/sdk

@telegram-apps/sdk-react — для React-проектов

npm install @telegram-apps/sdk-react

import { useInitData, useMainButton } from '@telegram-apps/sdk-react';

function OrderPage() {
  const initData = useInitData();
  const mainButton = useMainButton();

  // Данные пользователя доступны сразу
  const user = initData?.user;

  const handleOrder = () => {
    mainButton.setText('Оформить заказ');
    mainButton.show();
    mainButton.on('click', () => {
      // отправляем заказ на бэкенд
    });
  };

  return (
    <div>
      <h1>Привет, {user?.firstName}!</h1>
      <button onClick={handleOrder}>Выбрать</button>
    </div>
  );
}

Подробный пошаговый туториал с настройкой Vite, роутинга и компонентов — в нашей статье «Создаём Telegram Mini App на React».

Шаг 3: Инициализация и данные пользователя

Что внутри initDataUnsafe

import { retrieveLaunchParams } from '@telegram-apps/sdk';

const { initDataRaw, initData } = retrieveLaunchParams();

// initData.user содержит:
// - id: number          — Telegram ID пользователя
// - firstName: string   — имя
// - lastName?: string   — фамилия
// - username?: string   — @username
// - languageCode?: string — язык (ru, en, ...)
// - isPremium?: boolean — Telegram Premium

Валидация на сервере

Telegram подписывает initDataRaw HMAC-ключом, который генерируется из токена вашего бота. Алгоритм проверки:

import hmac
import hashlib
from urllib.parse import parse_qs

def validate_init_data(init_data_raw: str, bot_token: str) -> bool:
    parsed = parse_qs(init_data_raw)
    received_hash = parsed.get("hash", [""])[0]

    # Собираем строку для проверки
    data_pairs = []
    for key, values in sorted(parsed.items()):
        if key == "hash":
            continue
        data_pairs.append(f"{key}={values[0]}")
    data_check_string = "\n".join(data_pairs)

    # Генерируем ключ из токена бота
    secret_key = hmac.new(
        b"WebAppData", bot_token.encode(), hashlib.sha256
    ).digest()

    # Считаем HMAC
    computed_hash = hmac.new(
        secret_key, data_check_string.encode(), hashlib.sha256
    ).hexdigest()

    return computed_hash == received_hash

Никогда не пропускайте этот шаг. Без валидации любой пользователь может представиться кем угодно.

Шаг 4: Архитектура Mini App

Типичная архитектура Telegram Mini App выглядит так:

┌──────────────────────┐
│  Telegram WebView     │
│  (React/Vue/Svelte)   │
│  + @telegram-apps/sdk │
└──────────┬───────────┘
           │ HTTPS
┌──────────▼───────────┐
│  Ваш бэкенд          │
│  (FastAPI / Express)  │
│  - валидация initData │
│  - бизнес-логика      │
│  - Telegram Bot API   │
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│  БД + внешние API     │
└───────────────────────┘

Что на фронте, что на бэке

Фронтенд деплоится как статика (Vercel, Netlify, свой VDS), бэкенд — как обычный API-сервер.

Шаг 5: Работа с UI-компонентами Telegram

MainButton — главная кнопка

Большая кнопка внизу экрана. Используется как основной CTA: «Оформить заказ», «Оплатить», «Подтвердить».

import { useMainButton } from '@telegram-apps/sdk-react';

function Checkout({ total }: { total: number }) {
  const mainButton = useMainButton();

  useEffect(() => {
    mainButton.setText(`Оплатить ${total} ₽`);
    mainButton.show();
    mainButton.on('click', handlePayment);

    return () => {
      mainButton.hide();
      mainButton.off('click', handlePayment);
    };
  }, [total]);

  return <CartItems />;
}

BackButton — кнопка «Назад»

Появляется в заголовке WebView. Обязательно включайте на вложенных экранах — без неё пользователь застрянет.

import { useBackButton } from '@telegram-apps/sdk-react';
import { useNavigate } from 'react-router-dom';

function ProductPage() {
  const backButton = useBackButton();
  const navigate = useNavigate();

  useEffect(() => {
    backButton.show();
    backButton.on('click', () => navigate(-1));
    return () => backButton.hide();
  }, []);

  return <ProductDetails />;
}

HapticFeedback — вибрация

Мелочь, которая делает приложение «живым». Используйте при нажатиях, успешных действиях, ошибках.

import { useHapticFeedback } from '@telegram-apps/sdk-react';

function LikeButton() {
  const haptic = useHapticFeedback();

  return (
    <button onClick={() => {
      haptic.impactOccurred('medium');
      toggleLike();
    }}>
      ❤️
    </button>
  );
}

Шаг 6: Адаптация под тему Telegram

У Telegram есть светлая и тёмная тема, и ваш Mini App должен подстраиваться. SDK даёт доступ к цветам текущей темы:

import { useThemeParams } from '@telegram-apps/sdk-react';

function App() {
  const theme = useThemeParams();

  return (
    <div style={{
      backgroundColor: theme.bgColor,
      color: theme.textColor,
    }}>
      <h1 style={{ color: theme.headerBgColor }}>
        Каталог
      </h1>
    </div>
  );
}

Шаг 7: Тестирование и отладка

Способы отладки

1. Telegram Desktop + DevTools

Для включения на macOS: запустите Telegram Desktop, быстро кликните 5 раз по иконке Settings — появится меню отладки.

2. Eruda — встроенная консоль

Для мобильного тестирования вставьте Eruda — это мобильный DevTools:

<script src="https://cdn.jsdelivr.net/npm/eruda"></script>
<script>eruda.init();</script>

Уберите перед продакшеном — но на этапе разработки это спасение.

3. Бот-тестировщик

Частые грабли при тестировании

CORS — бэкенд должен разрешать запросы с домена Telegram (https://web.telegram.org)
Кеширование — Telegram агрессивно кеширует WebView. Добавляйте ?v=hash к URL ресурсов или настройте правильные заголовки Cache-Control
Разные платформы — WebView на iOS, Android и Desktop ведут себя по-разному. Тестируйте на всех трёх

Шаг 8: Деплой и публикация

Когда всё работает локально, пора выкатывать в продакшен.

Фронтенд

Mini App — это статический сайт. Соберите его и разместите на любом хостинге с HTTPS:

npm run build

Результат сборки (папка dist или out) заливаете на сервер. На VDS — через nginx, на облаке — Vercel, Netlify, Cloudflare Pages.

Обновите URL в BotFather

Замените ngrok-адрес на продакшен-домен:

/mybots → выберите бота → Bot Settings → Menu Button → новый URL

Добавьте в Telegram Directory

Telegram Mini App vs VK Mini Apps

Если вы работаете на российском рынке, логичный вопрос — а может, VK Mini Apps? Кратко:

Аудитория: Telegram растёт быстрее, но VK по-прежнему силён в регионах
Монетизация: Telegram Payments проще в интеграции, VK Pay требует отдельной заявки
DX: у Telegram лучше SDK и документация, VK Mini Apps используют свой VKUI-фреймворк
Платформа: если уже есть Telegram-бот, Mini App — логичное расширение

Подробное сравнение с таблицами и рекомендациями — в статье VK Mini Apps vs Telegram Mini Apps.

Чеклист перед запуском

Пройдитесь по этому списку перед тем, как показать Mini App пользователям:

Как создать Telegram Mini App: полная инструкция для разработчика

Что потребуется для старта

Шаг 1: Регистрация Mini App в BotFather

Шаг 2: Выбор SDK

@telegram-apps/sdk — универсальный

@telegram-apps/sdk-react — для React-проектов

Шаг 3: Инициализация и данные пользователя

Что внутри initDataUnsafe

Валидация на сервере

Нужен Mini App?

Шаг 4: Архитектура Mini App

Что на фронте, что на бэке

Шаг 5: Работа с UI-компонентами Telegram

MainButton — главная кнопка

BackButton — кнопка «Назад»

HapticFeedback — вибрация

Шаг 6: Адаптация под тему Telegram

Шаг 7: Тестирование и отладка

Способы отладки

Частые грабли при тестировании

Шаг 8: Деплой и публикация

Фронтенд

Обновите URL в BotFather

Добавьте в Telegram Directory

Telegram Mini App vs VK Mini Apps

Чеклист перед запуском

Обсудим ваш проект?

Что дальше

Обсудим ваш проект?

Похожие статьи

Вы пишете Telegram Mini App неправильно. Вот доказательство

VK Mini Apps или Telegram: где бизнес зарабатывает больше в 2026

Создаём Telegram Mini App на React: пошаговый туториал

Как создать Telegram Mini App: полная инструкция для разработчика

Что потребуется для старта

Шаг 1: Регистрация Mini App в BotFather

Шаг 2: Выбор SDK

@telegram-apps/sdk — универсальный

@telegram-apps/sdk-react — для React-проектов

Шаг 3: Инициализация и данные пользователя

Что внутри initDataUnsafe

Валидация на сервере

Нужен Mini App?

Шаг 4: Архитектура Mini App

Что на фронте, что на бэке

Шаг 5: Работа с UI-компонентами Telegram

MainButton — главная кнопка

BackButton — кнопка «Назад»

HapticFeedback — вибрация

Шаг 6: Адаптация под тему Telegram

Шаг 7: Тестирование и отладка

Способы отладки

Частые грабли при тестировании

Шаг 8: Деплой и публикация

Фронтенд

Обновите URL в BotFather

Добавьте в Telegram Directory

Telegram Mini App vs VK Mini Apps

Чеклист перед запуском

Обсудим ваш проект?

Что дальше

Обсудим ваш проект?

Похожие статьи

Вы пишете Telegram Mini App неправильно. Вот доказательство

VK Mini Apps или Telegram: где бизнес зарабатывает больше в 2026

Создаём Telegram Mini App на React: пошаговый туториал