Как создать Mini Apps Telegram (Web App): пошаговая инструкция от идеи до деплоя. Примеры кода и мини-приложений
В пошаговой инструкции разбираемся, как создать Mini App в Телеграм самостоятельно: идея, окружение, frontend- и backend-часть, загрузка на хостинг git-репозиториев.
Предлагаем сделать мини-приложение, задеплоить и проверить, как оно работает. Сам веб ап простой: это визитка (портфолио) с услугами. Если нужна коммерческая разработка Mini App Telegram с интеграцией 1С, CRM, ОФД, ИИ, AR, VR, лучше заказать мини ап под ключ.
Команда ChatLabs создает мини-приложения Телеграм / Vk / Max для магазинов, промо и спецпроектов, автоматизации продаж в b2b, HR-процессов. Подробнее у @chatlabs_manager
Что такое Mini Apps Telegram (Web App) и как создают игры, магазины, спецпроекты
Telegram Web App (Telegram Mini Apps, TWA, TMA, мини-апы) — приложения, работающие внутри Телеграм. Визуально они выглядят просто как сайт в Телеграмме.
Разработка Mini Apps стала актуальной с 2022 года, когда Павел Дуров анонсировал новую технологию. Telegram Web Apps позволяют создавать кроссплатформенные продукты (игры, магазины, промо-приложения) без разработки отдельных приложений на iOS, Андроид, Windows. Цена разработки мини-приложения в Телеграм оказывается в 2–3 раза дешевле по сравнению с созданием софта для мобильных на Андроид или АйОС.
Альтернатива MiniApp Telegram в России — Vk Mini Apps. Создать мини-приложение, игру или промобота можно при помощи готовых библиотек — VK Bridge, VK Tunnel, VK Mini Apps Deploy, VKUI. Сделанные мини-приложения доступны в каталоге ВКонтакте или в Одноклассниках. При этом под Vk Mini Apps разработка ведется по аналогичной схеме: идея, аналитика, написание кода, тестирование, поддержка.
С 1 сентября 2025 на смартфонах российских пользователей будет предоставлен национальный мессенджер Max (Макс). Для Max создают чат-ботов и Mini App — магазины, промо (спецпроекты), автоматизация процессов. Российский мессенджер Макс открывает новые возможности для бизнеса. Сюда можно перенести ботов и мини-приложения из Телеграм или сделать Mini App для Max.
Примеры Mini Apps Telegram (Web App)
Разработка Телеграм Mini App позволяет создавать:
- Магазины в Телеграм. В мини-приложении реализованы оплата (ЮKassa, TON, SberPay, Apple/Google Pay), каталог с фильтрами, поиск, сервисы доставки (СДЭК, Boxberry), парсинг и автоматический расчет цен.
- Приложения для промо, спецпроектов, акций. Бренды запускают мини-приложения с играми, тестами и квизами, онлайн-викторинами, розыгрышами подарков, ML/AI-персонализацией, закрытым клубом, реферальной системой.
- Игры и TON-проекты. Кликеры, тапалки, Tap-To-Earn и другие проекты повышают вовлеченность за счет использования внутригровой валюты и TON balance.
Разработка Телеграмм Mini App позволяет реализовать любую функциональность для маркетинговой акции, запуска игры, автоматизации продаж в b2b или b2c. Примеры Telegram Web Apps и кейсы использования MiniApp помогут понять, как запустить проект для конкретного бизнеса.
Сделать сайт для Mini App Telegram или Vkontakte можно за 10–130 дней в зависимости от сложности. Простой мини ап из примера ниже создается за 1 вечер.
Примеры Mini App Телеграм: готовые мини-ап под Telegram
Если собрались создать мини эп тг (самостоятельно или с привлечением подрядчика), рекомендуем изучить примеры реализации MiniApp.
Среди них:
- игра-кликер в Telegram Mini App — тапалка в Телеграм с бустами, рейтингом пользователей, реферальной системой;
- Mini App для торговли агропродукцией — маркетплейс для автоматизации торговли в b2b с каталогом товаров, сложным поиском аналогов, аукционом, фиксированными или прогрессивными ценами;
- Mini App для записи к психологам — приложение с тестами, бронированием консультаций, рейтингом психологов, оплатой услуг;
- Mini App для мороженого Магнат — спецпроект в Телеграм для промоактивности бренда (закрытый клуб, скидки, кастомные товары);
- Mini App для магазина цифровых товаров — интернет-магазин в Телеграм с поиском товаров, парсингом цен со сторонних площадок, приемом оплаты по СБП.
Надеемся, примеры помогут создать приложение для акции, магазина или автоматизации в b2b.
Архитектура Telegram Web App
Перед тем как сделать Mini App Telegram, нужно разобрать основные компоненты. Это:
- клиентская часть (frontend);
- серверная часть (backend);
- SDK (Software development kit — набор инструментов для Telegram);
- деплой, обновления, контроль версий.
Как работают Mini Apps Telegram
Перед тем как создать Web App Telegram (Mini App), уточним принцип работы: что происходит после клика на условный /start и как работает мини-приложение.
- Инициализация. Пользователь запускает мини-приложение в Телеграм.
- Загрузка. Telegram переходит к заданному URL, где расположен код Mini App. Страница подгружается стандартным браузером Telegram (WebView).
- Взаимодействие. Интерфейс Mini App доступен пользователю: кнопки, строки поиска, фильтры. Разработчики могут использовать возможности обычного веб-разработки (HTML / CSS / JS) и методы специального Telegram API (push-уведомление, обновление профиля).
- Синхронизация. Данные могут сохраняться локально или на сервере. Это важно для условного интернет-магазина в Телеграм: если пользователь добавил товар в корзину и не оплатил заказ, спустя время может зайти в приложение — и его корзина подгрузится. Синхронизация возможна через Telegram API или вручную (через сервер).
- Завершение. Пользователь закрывает Mini Apps Telegram и возвращается к Телеграм.
Когда разобрались с архитектурой и принципом работы мини-приложения, переходим к инструкции, как сделать Web App с нуля. Для новичков это может быть сложным, поэтому предлагаем сразу скачать исходники.
Как создать Telegram Web App в Телеграм: пошаговая инструкция с кодом
Идея простого Web App — разработка витрины (портфолио) с услугами. После запуска мини-приложения пользователь видит описание направлений работы и кнопку для заказа. Можно заказать интернет-магазин в Телеграм, чат-бот или Mini App. Файл с исходниками запрашивайте у @chatlabs_manager Чтобы запустить приложение Telegram Web App (Telegram Mini Apps), нужно: Пошагово с кодом разбираем, как создать Web App Telegram и запустить мини-приложение локально (а затем — и на сервере). Исходники миниапа запрашивайте у @chatlabs_manager Для начала нужно создать бота и получить токен. Пошаговая инструкция — «Создаем бота в BotFather: инструкция, команды, настройки». Для разработки Mini App Telegram нужна среда Node.js. Это «JavaScript runtime environment»: без нее код на JS не исполняется и не запускается. На момент написания статьи актуальна версия v24.2.0 (v22.16.0 LTS). Node.js доступен на Windows, MacOS, Linux, AIX. Открывать файлы можно и в блокноте или NotePad. Но для работы с кодом используются специальные инструменты — IDE (integrated development environment). Например, можно скачать и установить IntelliJ IDEA, Visual Studio, Sublime Text, NetBeans, Eclipse, Xcode, российская GigaIDE Desktop. Структура проекта для разработки Телеграм Мини Ап — это папка testert. В ней расположены файлы: Также для разработки нужны: Каждый из инструментов можно устанавливать отдельно, используя команды из списка ниже: $ npm install cors $ npm install dotenv —save $ npm install express $ npm install telegraf Но на самом деле все зависимости для работы с проектом мини-приложения в Телеграм уже находятся в package.json. Чтобы заинсталить их, достаточно: В результате автоматически установятся все те зависимости (dependencies). Ниже в инструкции представлен код из файла с зависимостями мини-приложения package.json: { «name»: «testert», «version»: «1.0.0», «main»: «index.js», «scripts»: { «test»: "echo \"Error: no test specified\" && exit 1″ }, «keywords»: [], «author»: "", «license»: «ISC», «description»: "", «dependencies»: { «cors»: «^2.8.5», «dotenv»: «^16.5.0», «express»: «^5.1.0», «telegraf»: «^4.16.3» } } В будущем консоль потребуется еще не раз. Поэтому обязательно проверьте, в какой директории находитесь (и используйте cd для перехода из одной папки в другую). Мы же идем дальше и изучаем как сделать Web App в Телеграмме (Mini App Telegram). Frontend-часть Mini App Telegram — это визуал + функциональная составляющая. В нашем примере нужно заверстать страницу, на которой будут описаны услуги, а рядом с каждой — кнопка «Заказать». Сложный Frontend в коммерческой разработке пишут с использованием специальных библиотек и фреймворков — React, Angular. Пока же просто создаем мини-ап для новичков с минимальными дополнительными инструментами. В index.html находится не просто структура веб-страницы. Файл служит точкой входа: отсюда загружается основное приложение JavaScript, которое динамически рендерится браузером. В index.html находятся: , Структура файла index.html для Мини Эп в Телеграм: Автоматизируйте свой бизнес с помощью чат-ботов и мини-приложений Автоматизация бизнес-процессов в Telegram Интерактивные приложения внутри Telegram Полноценный магазин в Telegram Структура index.html может быть и другой. Все зависит от конкретного проекта. Обратите внимание, что в файлы уже навешены стили на элементы (class). Остается подключить их. Файл styles.css отвечает за стили: цвет кнопок, текста, заголовков Web App в Телеграм. Как создать дизайн мини-приложения, зависит от специфики конкретного проекта. В примере сделаем реализацию в фирменных цветах бренда. Код: * { box-sizing: border-box; margin: 0; padding: 0; font-family: ’Roboto’, Arial, sans-serif; } :root { —primary-color: #0088cc; —secondary-color: #006699; —bg-color: var(—tg-theme-bg-color, #ffffff); —text-color: var(—tg-theme-text-color, #222222); —button-color: var(—tg-theme-button-color, #0088cc); —button-text-color: var(—tg-theme-button-text-color, #ffffff); —secondary-bg-color: var(—tg-theme-secondary-bg-color, #f5f5f5); } body { background-color: var(—bg-color); color: var(—text-color); line-height: 1.6; } .container { width: 100%; max-width: 1200px; margin: 0 auto; padding: 0 20px; } .header { display: flex; justify-content: center; align-items: center; padding: 10px 0; border-bottom: 1px solid rgba(0,0,0,0.1); } .logo h1 { color: var(—primary-color); font-size: 2.5rem; font-weight: 700; } .main-content { padding: 20px 0; } .hero { text-align: center; margin-bottom: 30px; } .hero h2 { font-size: 2rem; margin-bottom: 15px; color: var(—text-color); } .hero p { font-size: 1.2rem; color: rgba(0,0,0,0.7); max-width: 700px; margin: 0 auto; } .services { display: flex; flex-wrap: wrap; justify-content: center; gap: 30px; } .service-card { background-color: var(—secondary-bg-color); border-radius: 8px; padding: 15px; width: 100%; max-width: 220px; text-align: center; box-shadow: 0 2px 8px rgba(0,0,0,0.08); transition: transform 0.3s ease; } .service-card:hover { transform: translateY(-3px); } .service-card i { font-size: 2rem; color: var(—primary-color); margin-bottom: 8px; } .service-card h3 { font-size: 1rem; margin-bottom: 8px; color: var(—text-color); } .service-card p { color: rgba(0,0,0,0.7); margin-bottom: 15px; font-size: 0.85rem; } .service-button { background-color: var(—button-color); color: var(—button-text-color); border: none; border-radius: 6px; padding: 7px 18px; font-size: 0.9rem; cursor: pointer; transition: opacity 0.3s; font-weight: 500; width: auto; min-width: 110px; margin: 0 auto; display: block; } .service-button:hover { opacity: 0.9; } .footer { text-align: center; padding: 30px 0; border-top: 1px solid rgba(0,0,0,0.1); margin-top: 30px; color: rgba(0,0,0,0.6); } @media (max-width: 768px) { .services { flex-direction: column; align-items: center; } .service-card { max-width: 100%; } .hero h2 { font-size: 1.8rem; } } В файле app.js находится JavaScript-код для инициализации и настройки веб-приложения Telegram Web App. Ниже код Mini App с комментариями (пояснениями): // Инициализация Telegram WebApp const tgApp = window.Telegram.WebApp; // Метод ready() уведомляет платформу о готовности отобразить приложение tgApp.ready(); // Задается цвет шапки (Telegram theme) tgApp.setHeaderColor(’secondary_bg_color’); // Добавляется обработчик DOMContentLoaded, после загрузки основного контента срабатывает showMainContent() document.addEventListener(’DOMContentLoaded’, () => { showMainContent(); }); // Показать основной контент function showMainContent() { // Применить тему приложения Mini App Telegram applyTelegramTheme(); // Установить event-хэндлеры для сервисных кнопок setupServiceButtons(); } // Установить click-хэндлеры для сервисных кнопок function setupServiceButtons() { const chatbotButton = document.getElementById(’chatbotButton’); const miniAppButton = document.getElementById(’miniAppButton’); const storeButton = document.getElementById(’storeButton’); if (chatbotButton) { chatbotButton.addEventListener(’click’, () => handleServiceRequest(’chatbot’)); } if (miniAppButton) { miniAppButton.addEventListener(’click’, () => handleServiceRequest(’miniapp’)); } if (storeButton) { storeButton.addEventListener(’click’, () => handleServiceRequest(’store’)); } } // Handle service request clicks function handleServiceRequest(serviceType) { // Получить информацию о пользователе const user = tgApp.initDataUnsafe?.user; const userId = user?.id || ’unknown’; const username = user?.username || ’unknown’; // Показать подтверждение tgApp.MainButton.setText(’СПАСИБО ЗА ЗАКАЗ’); tgApp.MainButton.show(); console.log(`User ${username} (${userId}) requested ${serviceType} service`); // В реальном приложении данные направляются на backend // For example: fetch(’/api/order’, { method: ’POST’, body: JSON.stringify({ serviceType, userId }) }); } // Применить цвета оформления Telegram function applyTelegramTheme() { document.documentElement.style.setProperty(’—tg-theme-bg-color’, tgApp.themeParams.bg_color); document.documentElement.style.setProperty(’—tg-theme-text-color’, tgApp.themeParams.text_color); document.documentElement.style.setProperty(’—tg-theme-button-color’, tgApp.themeParams.button_color); document.documentElement.style.setProperty(’—tg-theme-button-text-color’, tgApp.themeParams.button_text_color); document.documentElement.style.setProperty(’—tg-theme-secondary-bg-color’, tgApp.themeParams.secondary_bg_color); } Таким образом, в app.js создали код для простого мини-приложения в Телеграм. В коммерческой разработке нужны проверки безопасности, обработка ошибок, взаимодействие с базами данных. В реальных проектах появляются вопросы, как сделать оплату в Telegram Mini App, как подтягивать остатки из 1С и интегрироваться с сервисами доставки. Все это и многое другое делают разработчики студии ChatLabs. Узнавайте больше у @chatlabs_manager Разработка Mini App Telegram невозможна без баз данных (PostgreSQL, MySQL, Microsoft SQL Server, Apache Cassandra, Redis). Пока же при создании мини-приложения запускаем сервер на Express, который обслуживает статический html-файл и обеспечивает возможность просмотра веб-программы. В папке src находится файл index.js с кодом для создания мини-приложения: require(’dotenv’).config(); const express = require(’express’); const cors = require(’cors’); const { Telegraf } = require(’telegraf’); const path = require(’path’); // Инициализация бота с токеном const bot = new Telegraf(process.env.BOT_TOKEN); // Создаем экземпляр Express app const app = express(); // Задаем порт, на котором запустится сервер const PORT = process.env.PORT || 3000; // Включаем поддержку cors app.use(cors()); // Разбираем POST-запросы в формате JSON app.use(express.json()); // Предоставляем статику из папки public app.use(express.static(path.join(__dirname, ’../public’))); // Задаем роут для главной страницы Telegram Mini App app.get(’/’, (req, res) => { // Отправляем на клиента файл index.html res.sendFile(path.join(__dirname, ’../public/index.html’)); }); // Команда start открывает Web App bot.command(’start’, async (ctx) => { try { // Пытаемся отправить сообщение с кнопкой открытия мини-приложения в Телеграм await ctx.reply(’Welcome to our service:’, { reply_markup: { inline_keyboard: [ [{ text: ’Open Web App’, web_app: { url: process.env.WEBHOOK_DOMAIN } }] ] } }); // Обрабатываем ошибку и отправляем уведомление пользователю } catch (error) { console.error(’Error opening web app:’, error); ctx.reply(’Sorry, something went wrong.’); } }); // Добавляем альтернативную команду — /webapp (аналог /start) bot.command(’webapp’, async (ctx) => { try { await ctx.reply(’Open our web app:’, { reply_markup: { inline_keyboard: [ [{ text: ’Open Web App’, web_app: { url: process.env.WEBHOOK_DOMAIN } }] ] } }); } catch (error) { console.error(’Error sending web app button:’, error); ctx.reply(’Sorry, something went wrong.’); } }); // Обрабатываем ошибки bot.catch((err, ctx) => { console.error(`Bot error for ${ctx.updateType}:`, err); }); // Запускаем (лончим) бота в Телеграм bot.launch() .then(() => console.log(’Bot started successfully’)) .catch(err => console.error(’Failed to start bot:’, err)); // Регистрируем обработчика сигнала SIGINT для плавной остановки process.once(’SIGINT’, () => bot.stop(’SIGINT’)); // То же самое для SIGTERM process.once(’SIGTERM’, () => bot.stop(’SIGTERM’)); // Запускаем Express server на указанном порте app.listen(PORT, () => { console.log(`Server is running on port ${PORT}`); console.log(`Web app available at: ${process.env.WEBHOOK_DOMAIN || `http://localhost:${PORT}`}`); }); Таким образом, сделали сервер для TMA Telegram. == Можно не запускать локально, а сразу перейти к следующим стадиям — залив на Гитхаб и деплой на сервер == При локальном запуске кода на машине (компьютере) нужно поставить веб-хук Телеграма. Для этого используется технология, которая дает возможность выкинуть чужую машину в сеть, а она будет проксировать трафик на локальное устройство. Чтобы все работал нужен дополнительный инструмент вроде Ngrok. Он скачивает все запросы, которые пришли по веб-хуку, а затем проксирует на локальную машину. Это нужно, чтобы локально тестировать приложение в Телеграм и видеть, работает функционал или нет. Если простыми словами, Ngrok создаст endpoint в сети. На этот эндпоинт можно будет зайти. Он перехватывает запросы, логирует и повторяет их так, как будто бы локальная машина развернута в сети. Ngrok — это утилита обратного прокси-сервера для доступа внутренних служб к Интернету посредством маршрутизации трафика через облачную сеть. ПО создает видимость, что ваш локальный веб-сервер (например, компьютер) размещен на поддомене ngrok.com. В России могут быть проблемы с доступами и оплатой, поэтому можно обратить внимание на альтернативы: Пошаговая инструкция, чтобы запустить мини-приложение локально с помощью Ngrok: Запустить контейнер. Команда: testert $docker run -d —rm -it —network host -p 4040:4040 -e NGROK_AUTHTOKEN=$NGROK_AUTHTOKEN ngrok/ngrok:alpine http localhost:3000 —log stdout Проверить статус контейнера Ngrok. Команда: docker ps -a Если все верно, можно зайти на localhost:4040/inspect/http, увидеть список реквестов и получить ссылку на proxy reverse. Дальше ее нужно вставить в .env, чтобы мини-приложение запустилось локально. В будущем она может использоваться для дебага и отслеживания событий и веб-хукам. Далее нам необходимо заменить в папке .env наш webhook url. Обратите внимание, что нужно подставить свой BOT TOKEN, PORT и WEBHOOK_DOMAIN. Когда все сделано, необходимо вернуться в папку и запустить приложение: testert node src/index.js В консоли показывается, где доступен созданный Web App Telegram. Для проверки заходим в бота и запускаем Telegram Mini App стандартным /start. После клика на «Open Web App» запускается мини-приложение в Телеграм. Таким образом, создали Telegram Mini App и запустили локально на машине (компьютере). Разработчики жалуются: проблема TMA в отсутствии адекватной тестовой среды (есть вопросы, как тестово развернуть и проверить функционал). Для тестирования и отладки Телеграм предоставляет специфическую среду — Test Environment. Также можно использовать консоль, просмотр дерева элементов и сетевых запросов. В пошаговой инструкции ниже заливаем проект на гитхаб (но можно использовать и другие системы — российский GitVerse, иностранный Меркурий и прочие). Пошаговая инструкция, как залить код Телеграм Mini App на GitHub: Перейти в нужную директорию. Команда: cd <название папки> Создать новый репозиторий в Git. Используется: git init Сделать Commit Changes (закоммитить код). Выбрать файлы для коммита, оставить commit message, указать автора, выбрать чекеры и т.д. Когда все настройки выставлены, нажать commit (аналог git commit -m «first commit»). Запушить код на GitHub — отправить изменения на репозитории. Команда: git push -u origin main Таким образом, создали мини-приложение в Телеграм и запушили на Git. Используя SSH HTTP отправляем файлы на удаленную машину. Для доступа нужны логин, пароль и IP-адрес. Они выдаются в формате: Команда для загрузки в консоли (upload sources): scp -r ./ login@91.31.11.99:/home/webapp Далее необходимо проверить, что файлы действительно скопировались на удаленную машину, а в директории есть все необходимые файлы. Команда: login@91.31.11.99:/home/webapp ls -la В консоли видно количество файлов, структура проекта и иные данные. Далее устанавливаем версию nvm (Node Version Manager) — это инструмент, который управляет версиями node.js и npm. Команда в консоли: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash Через nvm устанавливают нужную версию Node.js, а затем проверяют ее: node -v В консоли можно увидеть, что установлена версия node v22.16.0 (nvm v18.9.2). Затем запускаем установку пакетов командой: npm i Затем нужно запустить скрипт, который в свою очередь запустит веб-приложение и начнет слушать: node src/index.js Если открыть веб-ап и написать сообщение, приложение ответит. Web App запустится. Таким образом, задеплоили мини-прилжение Телеграм на удаленную машину, запустили и проверили: все работает корректно. Создать сложные мини-приложение проще, когда есть готовые инструменты. Ниже разберем, какие библиотеки, фреймворки и решения упрощают разработку мини-аппов в Телеграм. Подходят для заказной (коммерческой) разработки Telegram Mini Apps на Python и JavaScript/TypeScript. Python: JavaScript / TypeScript: UI Kits (Юай Киты) — это набор готовых компонентов, чтобы быстро создавать интерфейсы. Упростить и ускорить разработку Mini App Telegram можно с использованием: На GitHub можно скачать готовые темплейты (Template) — шаблоны, позволяющие быстро создать сложное приложение для Телеграмм. Например, доступны: Дока Телеграм для начинающих и опытных разработчиков: В пошаговой инструкции с примерами кода рассмотрели, как сделать Telegram Web Apps и запустить сайт-визитку. TMA позволяют создавать сложные проекты: игры, магазины, спецпроекты (промоактивности, маркетплейсы, сообщества (коммьюнити). Мы в ChatLabs создаем мини-приложения для Телеграм, Вконтакте, Max. В кейсах делимся, как решали сложные задачи разработки: обучали нейросеть под медицинский домен, создавали маркетплейсы, парсили PlayStation Store, помогали проводить тендеры и организовывать аукционы. Подписывайтесь на Телеграм-канал и узнавайте первыми о новых фишках и проектах! Есть идея создать интернет-магазин, тапалку, спецпроект (розыгрыш, промо) или другой сервис в Телеграм? Напишите @chatlabs_manager
Шаг 1. Подготовка окружения
Шаг 2. Клиентская часть
index.html
,
,
ChatLabs
Разработка решений для бизнеса в Telegram
Заказать чат-бот
Заказать Mini App
Заказать интернет-магазин
styles.css
app.js
Шаг 3. Создание бэкенда
Шаг 4. Локальный запуск Telegram Mini App
Шаг 5. Загрузка на GitHub
Шаг 6. Деплой и развертывание Telegram Mini App на сервере
Как сделать Mini App Telegram: шаблоны, библиотеки, UI Kits
Библиотеки для чат-ботов и Mini App Telegram
UI Kits (User Interface Kit)
Шаблоны Mini Apps
Официальная документация для разработки
Заключение