Привет! Мы Дима и Илья, работаем в команде ТМА-разработки Doubletapp и расскажем, как создать Telegram Mini App на стеке React + Python.

Telegram Mini Apps — это мощный инструмент, который позволяет создавать интерактивные веб-приложения, работающие прямо внутри мессенджера. Они идеально подходят для игр, маркетплейсов, сервисов бронирования и многого другого.

В этом туториале мы разберем процесс создания Mini App:

• настроим проект

• создадим фронтенд на React с поддержкой Telegram SDK

• реализуем бэкенд на Python (Django)

• свяжем все компоненты и развернем приложение.

Для кого этот гайд?

Этот гайд предназначен для опытных разработчиков, которые хотят создать production-ready Mini App на стеке React + Python. Мы не будем подробно разбирать базовые концепции, как разворачивать веб-приложение на этом стеке, а сосредоточимся на реализации рабочего, оптимизированного и безопасного решения.

Цель статьи

Наша цель — не просто разобрать теорию, а провести вас через весь процесс разработки, от настройки окружения до развертывания рабочего приложения. Этот материал поможет вам избежать подводных камней и значительно ускорить процесс разработки.

Основные концепции и термины

В этом разделе мы рассмотрим, что такое Telegram Mini Apps, какие возможности они предоставляют разработчикам и пользователям, а также разберём ключевые отличия Mini Apps от обычных ботов Telegram. Это поможет лучше понять, в каких случаях Mini Apps могут быть более эффективным решением для реализации вашего проекта.

Что такое Telegram Mini Apps?

Telegram Mini Apps (TMA) — это веб-приложения, которые запускаются внутри Telegram и позволяют пользователям взаимодействовать с сервисами без необходимости устанавливать отдельные мобильные приложения. Они работают в встроенном браузере Telegram, обеспечивая бесшовную авторизацию, удобный пользовательский опыт и глубокую интеграцию с мессенджером. TMA функционируют на всех популярных платформах: Android, iOS, Windows, Mac и Linux.

Mini Apps используют стандартные веб-технологии, такие как HTML, CSS и JavaScript, и взаимодействуют с Telegram через Web Apps API. Это даёт разработчикам возможность создавать приложения с гибким интерфейсом, доступом к данным пользователя (например, имени и контактной информации) и возможностью обмена сообщениями через ботов.

Таким образом, Mini Apps — это мощный инструмент для создания интерактивных сервисов, которые работают прямо в Telegram, упрощая взаимодействие пользователей с цифровыми продуктами.

Чем Mini Apps отличаются от обычных ботов?

Хотя Mini Apps и боты Telegram работают внутри мессенджера, у них разные принципы взаимодействия с пользователем и сценарии использования.

1. Интерфейс и пользовательский опыт

Боты Telegram взаимодействуют с пользователем через текстовые команды и кнопки в сообщениях. Их интерфейс ограничен возможностями мессенджера. Mini Apps предоставляют полноценный графический интерфейс, позволяя создавать удобные и интерактивные веб-приложения внутри Telegram.

2. Техническая реализация

Боты работают через Telegram Bot API, который управляет сообщениями, командами и кнопками. Mini Apps, в свою очередь, используют Web Apps API, позволяя запускать веб-приложения, которые взаимодействуют с Telegram через JavaScript.

3. Сценарии использования

Боты чаще применяются для автоматизации задач, ведения рассылок, поддержки клиентов и работы с чат-ботами.

Mini Apps подходят для более сложных сервисов, таких как интернет-магазины и сервисы доставки, финансовые приложения и платежные системы, игры и развлекательные платформы, CRM-системы и инструменты для бизнеса.

Таким образом, Mini Apps дополняют функциональность ботов, расширяя возможности взаимодействия с пользователями и предлагая более удобный и гибкий опыт работы в Telegram.

Подготовка к разработке

Прежде чем приступить к созданию Telegram Mini App, важно грамотно подготовить рабочее окружение и заложить архитектурные основы проекта. В этом разделе мы пошагово разберём подготовку к разработке:

• настроим локальное окружение для удобной и изолированной работы;

• организуем проект в виде монорепозитория, чтобы упростить управление фронтендом и бэкендом в рамках одного репозитория;

• создадим Telegram-бота, через которого будет запускаться Mini App;

• инициализируем фронтенд-приложение на Vite + React;

• настроим Docker, чтобы обеспечить единообразную среду разработки и продакшен-окружение;

• используем прокси-инструменты, чтобы удобно можно было тестировать Mini App;

• настроим Nginx.

• аутентификацию пользователей будем производить через Init Data

• подключение Telegram Web Apps SDK (@telegram-apps/sdk-react)

Настройка локального окружения

Первым делом важно подготовить полноценную локальную среду, в которой одновременно запускаются и фронтенд, и бэкенд. Это критично не только для тестирования функционала, но и для корректной работы авторизации через Telegram. Для изоляции окружения и удобного запуска всех компонентов мы будем использовать Docker — он позволит унифицировать запуск как на локальной машине, так и в продакешне, избавив вас от сложной ручной настройки. 

Особенность Mini Apps в том, что авторизация пользователей происходит через валидацию Init Data с помощью конкретного токена Telegram-бота. Это значит, что бэкенд должен проверять подпись Init Data, сверяясь с токеном бота, через которого запускается Mini App. В результате каждому разработчику необходимо создать собственного Telegram-бота и использовать его токен для локальной разработки. Таким образом, даже фронтенд-разработчику обязательно нужно запускать локальный backend, чтобы обеспечить полноценную авторизацию и протестировать поведение приложения в боевых условиях.

Также в проектах мы используем подход монорепозитория: и фронтенд, и бэкенд находятся в одном репозитории, но разделены по папкам (/frontend, /backend). Это решение значительно упрощает:

• совместную разработку,

• настройку CI/CD,

• согласование версий API,

• внесение правок,

• единое управление зависимостями и конфигурацией.

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

Создание бота

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

Если у вас ещё нет бота, вы можете создать его через @BotFather. Мы не будем подробно останавливаться на этом процессе — он стандартный и хорошо описан в официальной документации Telegram.

Что нужно сделать:

1. Получите токен бота.

2. Задайте URL Mini App'а.
   В диалоге с @BotFather откройте меню: Bot Settings → Configure Mini App → Edit Mini App URL

3. Настройте кнопку запуска Mini App
   Для удобства пользователю можно добавить кнопку, открывающую Mini App. Это можно сделать через @BotFather: Bot Settings → Edit Menu Button

Создание пользователя при старте

В Mini App важно, чтобы пользователь в базе данных создавался автоматически при любом взаимодействии с ботом, а не только при запуске через команду /start. Telegram передаёт объект пользователя (from) почти во всех типах обновлений, и это даёт возможность централизованно обрабатывать создание. Реализуем middleware, которая будет:

• извлекать данные Telegram-пользователя из любого update;

• создавать пользователя в БД, если он ещё не зарегистрирован;

• сохранять его в context, чтобы удобно использовать в последующей логике.

import typing

import structlog
from dependency_injector.wiring import Provide
from dependency_injector.wiring import inject
from telegram import Update
from telegram.ext import CallbackContext

from project.containers import Container

if typing.TYPE_CHECKING:
    from users.services import UserService

logger = structlog.get_logger(__name__)


@inject
def update_or_create_user(
    update: Update,
    context: CallbackContext,
    user_service: 'UserService' = Provide[Container.user_service],
) -> None:
    if update.message is None:
        return

    tg_user = update.message.from_user
    if not tg_user:
        logger.debug('No Telegram user found in the update message')
        return

    user, created = user_service.update_or_create(tg_user)

    structlog.contextvars.bind_contextvars(
        user_id=user.id,
        messenger_user_id=update.message.from_user.id,
    )

    if created:
        logger.info('New user created')

    context.user_data['user'] = user

Готово! Теперь у нас в каждом обработчике будет передаваться наш пользователь.

После настройки бота можно переходить к следующему шагу — созданию фронтенд-приложения, которое будет запускаться внутри Telegram.

Инициализация React-приложения

Ранее мы писали, как создаем React-приложение. В этой статье рассмотрим особенности проекта для TMA. Конфигурация нашего проекта мини-приложения в Telegram отличается наличием функции для инициализации приложения.

import { retrieveLaunchParams } from '@telegram-apps/sdk-react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import 'config/i18n/i18n.ts'
import { init } from './utils/init.ts'

const root = ReactDOM.createRoot(document.getElementById('root')!)

try {
  init(retrieveLaunchParams().startParam === 'debug' || import.meta.env.DEV)
  root.render(<App />)
} catch (e) {
  console.error(e)
}

Инициализация мини-приложения происходит до рендера React-приложения.

import {
  backButton,
  viewport,
  themeParams,
  miniApp,
  initData,
  $debug,
  init as initSDK
} from '@telegram-apps/sdk-react'

export function init(debug: boolean): void {
  $debug.set(debug)

  initSDK()

  if (!backButton.isSupported() || !miniApp.isSupported()) {
    throw new Error('ERR_NOT_SUPPORTED')
  }

  backButton.mount()
  miniApp.mount()
  themeParams.mount()
  initData.restore()
  void viewport
    .mount()
    .catch(e => {
      console.error('Something went wrong mounting the viewport', e)
    })
    .then(() => {
      viewport.bindCssVars()
    })

  miniApp.bindCssVars()
  themeParams.bindCssVars()
}

В данном проекте мы использовали пакет @telegram-apps/sdk-react 2 версии. SDK изначально не инициализирован и не готов к работе — все его компоненты остаются в несмонтированном состоянии. Для того, чтобы начать использовать SDK и получить доступ как к функциям монтирования компонентов, так и к другим доступным методам, необходимо вызвать функцию init. Затем мы инициализируем компоненты — backButton, miniApp, themeParams, viewport, необходимые нам в дальнейшей работе.

Настройка Docker

Наш проект является монорепозиторием. Поэтому для локального запуска мы используем отдельный Docker конфиг, он отличается тем, что поддерживает hot reload, что важно для разработки frontend`а.

Для режима разработки мы добавили специальный docker-compose.local.yml конфиг. Он отличается наличием дополнительного vite сервиса — фронтенд, запущенный в режиме разработки и модифицированного nginx конфига, в котором проксируется сервис vite:

services:
...
 vite:
    build:
      context: .
      dockerfile: ./docker/vite/Dockerfile
      args:
        API_BASE_URL: ${API_BASE_URL}
    volumes:
      - ./frontend:/app
      - /app/node_modules
    restart: always
    ports:
      - "5173:5173"

  nginx:
    image: "${IMAGE_NGINX}"
    build:
      context: .
      dockerfile: docker/nginx-local/Dockerfile
      ...

docker-compose.local.yml

http {
    ...
    server {
        ...
        location / {
            proxy_pass http://vite:5173;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }
    }
}

nginx.conf 

При этом vite приложение запускается в режиме разработки:

FROM node:21-alpine as build

ARG API_BASE_URL

ENV VITE_API_BASE_URL=$API_BASE_URL

WORKDIR /app

COPY frontend/package*.json ./
RUN npm install

COPY ./frontend .

EXPOSE 5173

CMD ["npm", "run", "start", "--", "--host", "0.0.0.0"]

Прокси-инструменты для фронтенда

На этапе разработки мини-приложения Telegram требуют действительного URL-адреса для отображения и тестирования в клиенте Telegram. Ссылка на localhost несовместима с требованиями BotFather к URL-адресам мини-приложений из-за строгого требования Telegram к протоколу HTTPS. Для тестирования мини-приложения на реальных клиентах Telegram (мобильных или настольных) необходим URL-адрес HTTPS.

Чтобы преодолеть этот разрыв, разработчики обычно используют сервисы проксирования публичных URL.

У нас был опыт использования нескольких сервисов:

• ngrok — сервис, доступный только с VPN. ngrok предлагает бесплатный тариф, но он имеет определенные ограничения, включая, один статический домен, 20 000 HTTP-запросов в месяц и лимит исходящего трафика в 1 ГБ. При истечении лимитов можно пересоздать аккаунт.

• localtunnel — служит полностью бесплатной альтернативой ngrok, предлагая аналогичную функциональность. Его можно легко установить через npm (npm install -g localtunnel). На моем опыте приходилось часто перезапускать localtunnel, а вместе с этим и менять ссылку на приложение в BotFather и в переменных окружения.

• Из платных утилит, доступных в России, мы попробовали Tuna. Она предоставляет возможность создать сразу несколько доменов, работает стабильно.

Аутентификация пользователей через Init Data

При разработке Telegram Mini Apps одним из ключевых аспектов является аутентификация пользователей. Telegram предоставляет механизм передачи данных пользователя через Init Data, который может быть использован для идентификации и проверки подлинности. Однако разработчикам необходимо правильно проверять эти данные, а также учитывать возможные взаимодействия с третьими сторонами.

Проверка данных, полученных через TMA

Когда запускается приложение, то клиент сохраняет Init Data в объекте браузера — Telegram.WebApp.initData (если TMA запущено через keyboard button или inline mode, то объект будет пустой). Init Data передается в виде строки, содержащей такие параметры, как информация о пользователе (user), хэш (hash), время генерации (auth_date) и другие сведения. Полное описание объекта можно прочитать на сайте документации.

Init Data нужно передавать в HTTP заголовке запроса. Далее мы на backend проверяем подлинность этих данных и выполняем механизм аутентификации/авторизации. Для проверки необходимо выполнить следующие шаги:

1. Извлечь параметры: полученные данные необходимо разобрать, выделив ключевые параметры.

2. Вычислить контрольную подпись: 

   1. Исключить hash из набора параметров.

   2. Отсортировать параметры в алфавитном порядке и соединить их в строку вида key=value.

   3. Вычислить HMAC-SHA256 с секретным ключом, сформированным с помощью токена бота.

3. Сравнить контрольную подпись: если вычисленный хэш совпадает с переданным hash, данные можно считать подлинными.

4. Проверить auth_date: если метка времени слишком старая (например, более нескольких часов), данные могут быть недействительными.

Более подробное описание алгоритма есть на сайте документации Telegram.

Для удобства работы с Init Data в TMA мы в компании сделали небольшую библиотеку. С помощью неё можно легко реализовать механизм аутентификации/авторизации пользователей на backend.

Пример на Django:

Рассмотрим пример на Django. Создадим middleware для авторизации пользователя, которая будет:

• проверять подпись Init Data,

• извлекать из него данные пользователя (ID, имя, username и т.д.),

• и — что особенно важно — создавать нового пользователя в базе, если он ещё не зарегистрирован. Это обязательный шаг, потому что Mini App может быть открыт не только через команду /start в боте, но и напрямую по ссылке. В таком случае пользователь попадает сразу в frontend, минуя любую начальную инициализацию на стороне Telegram-бота.

Сначала зададим нужные переменные в settings.py:

from telegram_webapp_auth.auth import generate_secret_key

# другие настройки...

TELEGRAM_BOT_TOKEN = env.str('TELEGRAM_BOT_TOKEN')
TELEGRAM_SECRET_KEY = generate_secret_key(TELEGRAM_BOT_TOKEN)

Реализуем middleware:

from django.conf import settings
from django.http import HttpRequest
from django.http import HttpResponse
from telegram_webapp_auth.auth import TelegramAuthenticator
from telegram_webapp_auth.errors import InvalidInitDataError
from users.services import UserService


class TMAAuthorizationMiddleware:
    def __init__(self, get_response) -> None:
        self.get_response = get_response
        self._telegram_authenticator = TelegramAuthenticator(settings.TELEGRAM_SECRET_KEY)
        self._user_service = UserService()

    def __call__(self, request: HttpRequest) -> HttpResponse:
        auth_cred = request.headers.get('Authorization')

        try:
            init_data = self._telegram_authenticator.validate(auth_cred)
        except InvalidInitDataError:
            # TODO: обработать исключение ExpiredInitDataError
            # TODO: обработать случай, если невалидная Init Data
            pass

        if not init_data.user:
            # TODO: обработать случай если в объекте Init Data нет информации о пользователе
            pass
        
        current_user = self._user_service.update_or_create(init_data.user)
        request.user = current_user  # добавляем пользователя в объект запроса

        response = self.get_response(request)

        return response

Добавим созданную middleware в настройки MIDDLEWARE в settings.py:

MIDDLEWARE = [
    # другие middleware
    'path.to.TMAAuthorizationMiddleware',
]

Готово! Теперь мы можем авторизовывать нашего пользователя из TMA.

Проверка Third-Party данных

В Telegram также добавили возможность валидировать Init Data со стороннего бота. Для этого нам достаточно знать только ID нужного бота. Это может пригодиться, когда нужно сделать интеграцию между backend-ами разных ботов.

Целостность данных может быть проверена путем проверки полученного параметра signature, который является закодированным в base64url представлением подписи Ed25519. Проверка выполняется с использованием открытого ключа, предоставленного Telegram.

Данный алгоритм также реализован в нашей библиотеке.

Обмен Init Data на JWT

Некоторые разработчики предпочитают обменивать Init Data на JWT-токен после первой инициализации. Это выглядит так:

1. Frontend отправляет Init Data на backend.

2. Backend валидирует его и создаёт JWT.

3. JWT возвращается на клиент и сохраняется (в localStorage).

4. Все дальнейшие запросы frontend отправляет с этим токеном.

Плюсы:

• Позволяет гибко управлять сроком жизни сессии.

• Универсальность – можно передавать данные внутри токена.

• Кросс-доменность – подходит для микросервисов.

Минусы:

• localStorage может не сохраняться в Telegram Mini App: На некоторых устройствах (iOS, Linux Desktop) Telegram WebView изолирован. Перезапуск Mini App может очищать кэш и storage. И с этим, к сожалению, ничего не поделать.

• Потеря токена = повторная авторизация, что влечёт за собой лишние запросы.

Из-за того, что приложение Telegram не всегда сохраняет localStorage мы  предпочитаем использовать авторизацию через Init Data в простых проектах, а не через JWT — она безопасная, простая и не зависит от поведения WebView Telegram. 

Подключение Telegram SDK React

Пакет @telegram-apps/sdk-react предоставляет набор компонентов и методов, которые позволяют разработчикам беспрепятственно взаимодействовать с нативными элементами пользовательского интерфейса Telegram и функциями платформы.

Описание возможностей SDK

Приведу несколько примеров:

BackButton — наверно самый часто использующийся компонент, управляет кнопкой «назад», расположенной в заголовке мини-приложения. Ее основная цель — облегчить навигацию по истории маршрутизации приложения, хотя ее событие клика должно быть явно обработано разработчиком, поскольку оно не вызывает никаких встроенных действий. Мы реализовали хук для удобного использования этой кнопки:

import { backButton } from '@telegram-apps/sdk-react'
import { useEffect } from 'react'

export const useAppBackButton = (handler: () => void) => {
  useEffect(() => {
    backButton.onClick(handler)

    return () => {
      backButton.offClick(handler)
    }
  }, [backButton])

  return {
    isVisible: backButton.isVisible,
    showButton: backButton.show.bind(backButton),
    hideButton: backButton.hide.bind(backButton)
  }
}

Viewport предоставляет данные о представлении мини-приложения в клиенте Telegram. Этот объект предоставляет важную информацию, такую как width, height, stability (указывает, ожидается ли изменение размера), expansion (достигла ли максимальной высоты) и статус fullscreen. Разработчики могут программно развернуть приложение, используя функцию expand:

if (viewport.expand.isAvailable()) {
  viewport.expand()
}

или запросить полноэкранный режим

if (viewport.requestFullscreen.isAvailable()) {
  await viewport.requestFullscreen();
}

что особенно полезно для игр или медиа-приложений. Также viewport предоставляет некоторые полезные данные в CSS переменных:

if (viewport.bindCssVars.isAvailable()) {
  viewport.bindCssVars();
  // Создает CSS переменные:
  // --tg-viewport-height: 675px
  // --tg-viewport-width: 320px
  // --tg-viewport-stable-height: 675px
}

Функция ThemeParams позволяет мини-приложению адаптировать свой стиль в соответствии с текущей темой Telegram, выбранной пользователем. При вызове функции bindCssVars появляется возможность использовать CSS переменные:

if (themeParams.bindCssVars.isAvailable()) {
  themeParams.bindCssVars();
  // Создает CSS переменные:
  // --tg-theme-button-color: #aabbcc
  // --tg-theme-accent-text-color: #aabbcc
  // --tg-theme-bg-color: #aabbcc
  // ...
}

Это помогает приложению выглядеть более нативным и интегрированным. 

Объект miniApp позволяет устанавливать цвета хедера и фона мини-приложения:

if (
  miniApp.setHeaderColor.isAvailable()
  && miniApp.setHeaderColor.supports('rgb')
) {
  miniApp.setHeaderColor('#aabbcc');
  miniApp.headerColor(); // '#aabbcc'
}

if (miniApp.setBackgroundColor.isAvailable()) {
  miniApp.setBackgroundColor('#ffffff');
  miniApp.backgroundColor(); // '#ffffff'
}

Также этот объект имеет методы close для закрытия мини-приложения и ready для сигнализирования мини-приложению о том, что наше веб-приложение проинициализировано и его можно отображать.

Telegram предоставляет API для взаимодействия с виброоткликом устройства: объект hapticFeedback. Метод impactOccurred позволяет воспроизводить вибрацию на любой вкус — light, medium, heavy, rigid, soft. Это может быть очень полезно для UX-составляющей приложения.

if (hapticFeedback.impactOccurred.isAvailable()) {
  hapticFeedback.impactOccurred('medium');
}

Объект swipeBehavior позволяет контролировать скрытие мини-приложения жестом пролистывания. Если ваше приложение вертикально занимает место больше одного экрана, то лучше отключить данный жест:

if (swipeBehavior.disableVertical.isAvailable()) {
  swipeBehavior.disableVertical()
}

Также есть другие нативные компоненты, доступные в SDK, — это popup, main button, settings button, qr scanner и другие. Они позволяют добиться вида нативного приложения.

Ключевые функции и параметры SDK, авторизация с Init Data

Авторизация клиентских запросов в нашем приложении происходит при помощи объекта initDataRaw из метода retrieveLaunchParams:

const { initDataRaw } = retrieveLaunchParams()

export const http = axios.create({
  baseURL: appConfig.api.baseUrl,
  headers: {
    Authorization: initDataRaw,
    'Content-Type': 'application/json'
  }
})

Тестирование и отладка

Перед запуском Mini App в продакшен важно обеспечить стабильную и предсказуемую работу на всех уровнях — от backend-логики до клиентского интерфейса в Telegram. Поскольку Telegram Mini Apps запускаются в окружении, где фронтенд и backend тесно связаны, а поведение может отличаться в зависимости от платформы (Android, iOS, Desktop, Web), отладка требует особого подхода.

В этом разделе мы разберём:

• как удобно отлаживать backend-часть, в том числе в условиях, когда нет готового Init Data;

• как тестировать Mini App на разных устройствах, чтобы убедиться в корректной работе SDK, адаптивности интерфейса и совместимости поведения;

Отладка Backend-части

При разработке Telegram Mini App важно наладить удобную и быструю отладку API. Telegram передаёт в Mini App специальный параметр Init Data, который используется для авторизации пользователя на сервере. Однако на этапе разработки работать с ним напрямую неудобно:

• Init Data можно получить только из работающего фронтенда внутри Telegram.

• Его необходимо каждый раз копировать. Это мешает быстрой отладке API и замедляет цикл разработки.

Чтобы ускорить отладку API локально, удобно ввести альтернативный режим авторизации, при котором вы передаёте user_id напрямую, минуя Init Data.

Как это реализовать:

• В middleware проверяйте, включён ли режим разработки (например, через settings.DEBUG).

• Если параметр X-Dev-User-ID передан в заголовках запроса — используйте его вместо Init Data.

• Создайте или найдите пользователя по этому ID и сохраните в request.user.

Пример middleware:

from django.conf import settings
from django.http import HttpRequest
from django.http import HttpResponse
from users.services import UserService

class DevAuthMiddleware:
    def __init__(self, get_response) -> None:
        self.get_response = get_response
        self._user_service = UserService()

    def __call__(self, request: HttpRequest) -> HttpResponse:
        auth_cred = request.headers.get('X-Dev-User-ID')
        if settings.DEBUG and auth_cred:
            user, _ = user_service.get_or_create(user_id=auth_cred)
            request.user = user

        return self.get_response(request)

Теперь вы можете использовать Postman, cURL или Swagger UI для запросов, просто передавая нужный ID.

Тестирование на разных устройствах

Для устройств Android основным интерфейсом отладки является Chrome DevTools, доступ к которому осуществляется через chrome://inspect/#devices в браузере Chrome на подключенном компьютере. Этот инструмент позволяет разработчикам проверять элементы DOM мини-приложения, отслеживать сетевые запросы, просматривать логи консоли и другое.

Аналогично для Telegram-клиента на iOS, Safari Web Inspector на Mac позволяет отладить приложение. После установления соединения между устройством iOS и машиной macOS разработчики могут использовать меню «Разработка» в Safari для проверки содержимого WebView, используя возможности, аналогичные Chrome DevTools, для отладки, проверки элементов и логирования консоли.

В ситуациях, когда удаленная отладка с помощью специфичных для платформы инструментов разработчика затруднена или недоступна, особенно для устройств iOS без доступа к машине macOS, npm-пакет Eruda предлагает альтернативу отладки в приложении. Eruda — это легковесная веб-консоль, которую можно интегрировать непосредственно в само мини-приложение. После добавления библиотеки в проект, ее необходимо инициализировать, вызвав eruda.init(). После развертывания и запуска мини-приложения в пользовательском интерфейсе приложения появится значок Eruda. Нажатие на этот значок отобразит консоль, предоставляющую базовые возможности отладки, такие как логирование, проверка элементов и мониторинг сети.

Деплой на продакшен

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

Общие рекомендации по продакшену

• Разносите окружения: локальная разработка, staging и production должны быть изолированы друг от друга. Чтобы не было ситуации, когда один стенд влияет на другой.

• Мониторьте логи и ошибки — например, с помощью Sentry, Prometheus + Grafana + Loki или других систем наблюдения.

• Для продакшена рекомендуется только webhook режим для работы Telegram бота:

  • он менее ресурсоёмкий,

  • работает быстрее (обновления приходят сразу),

  • легче масштабируется.

Рекомендации по безопасности

• Ограничьте время жизни Init Data – нельзя создавать вечноживущий токен.

• Ограничьте доступ к административным интерфейсам — только по IP, VPN или логину

• Ограничьте источники для CORS и CSP — Telegram WebView, ваш домен и нужные API

• Регулярно обновляйте зависимости и следите за CVE-уязвимостями!

• Защита от DDoS-атак – злоумышленник не дремлет.

• Настройте rate limit на всех API endpoint-ах  – не позволяйте клиентам эксплуатировать ваше API.

Кэширование и сжатие статики

• Минифицируйте и хэшируйте JS/CSS – это экономит трафик и ускоряет загрузку приложения.

• Включите Gzip или Brotli-сжатие – также ускоряет загрузку статики.

Кэширование запросов к backend API

Чтобы ускорить отклик и снизить нагрузку:

• Кэшируйте публичные и часто повторяющиеся GET-запросы. Делайте запросы идемпотентными.

• Используйте Redis/Memcached. Кэшируйте сами запросы.

• Включите поддержку Cache-Control. Используете кэш браузера.

Примеры кейсов

Несколько примеров из нашей практики

Мы создаём Telegram Mini Apps под самые разные задачи — от игр до e-commerce и сервисов. Вот часть реализованных проектов:

— Doubletapalka. Придумали механику, просчитали экономику, реализовали всё — от дизайна до backend-логики. Получилась динамичная игра с потенциалом для монетизации.
— Интернет-магазин мерча. Полноценный e-commerce прямо внутри Telegram — с нативной оплатой банковскими картами и криптовалютой. Мы разработали дизайн, фронтенд и backend.
— Сервис аренды авто. Разработали чистый и понятный интерфейс mini app — фокус на UX, удобство бронирования и визуальную лёгкость.
— CryptoFlow — карточная игра в духе Reigns. Реализована свайп-механика, сохранение игровых историй, ачивки, коллекция карт и покупки за Telegram Stars. Мы отвечали за весь фронт и backend.

Заключение

Telegram Mini Apps — это мощный инструмент для создания полноценных веб-приложений внутри мессенджера. В этом гайде мы разобрали ключевые шаги, которые помогут вам построить production-ready решение.

Краткое резюме пройденного материала

• Разобрались, что такое Mini Apps и чем они отличаются от ботов

• Подготовили окружение с Docker, Nginx и монорепозиторием

• Создали и настроили бота для работы с Mini App

• Реализовали авторизацию через Init Data и регистрацию пользователей

• Настроили фронтенд на Vite и backend на Django

• Рассмотрели отладку, тестирование и рекомендации деплоя

Если вы дошли до этого этапа — у вас в руках вся база для запуска собственного Mini App в Telegram. Удачи в продакшене! ?

Готовы внедрить Telegram Mini App в свой бизнес?
Если вы видите потенциал в TMA и хотите использовать этот инструмент с умом, мы готовы помочь. Наша команда разрабатывает решения, которые работают на результат — от удобных интерфейсов до глубокой интеграции с вашими процессами.

Обсудим вашу задачу — напишите нам на почту hi@doubletapp.ai или оставьте заявку через телеграм-бота.
Всё начинается с короткого диалога. Остальное мы берём на себя.

Дополнительные ресурсы

• https://core.telegram.org/bots/webapps#implementing-mini-apps – официальная документация от Telegram Mini Apps

• https://core.telegram.org/bots#3-how-do-i-create-a-bot – создание бота

• https://t.me/doubletapp/991 – библиотека для валидации Init Data с помощью Python.

Больше кейсов и новостей – в Telegram-канале Doubletapp. Подпишись!