Как создать Mini Apps Telegram (Web App): пошаговая инструкция от идеи до деплоя. Примеры кода и мини-приложений

В пошаговой инструкции разбираемся, как создать Mini App в Телеграм самостоятельно: идея, окружение, frontend- и backend-часть, загрузка на хостинг git-репозиториев.

Предлагаем сделать мини-приложение, задеплоить и проверить, как оно работает. Сам веб ап простой: это визитка (портфолио) с услугами. Если нужна коммерческая разработка Mini App Telegram с интеграцией 1С, CRM, ОФД, ИИ, AR, VR, лучше заказать мини ап под ключ.

Команда ChatLabs создает мини-приложения Телеграм / Vk / Max для магазинов, промо и спецпроектов, автоматизации продаж в b2b, HR-процессов. Подробнее у @chatlabs_manager

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 App позволяет создавать:

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

Сделать сайт для Mini App Telegram или Vkontakte можно за 10–130 дней в зависимости от сложности. Простой мини ап из примера ниже создается за 1 вечер.

Если собрались создать мини эп тг (самостоятельно или с привлечением подрядчика), рекомендуем изучить примеры реализации MiniApp.

Среди них:

Надеемся, примеры помогут создать приложение для акции, магазина или автоматизации в b2b.

Перед тем как сделать Mini App Telegram, нужно разобрать основные компоненты. Это:

Перед тем как создать Web App Telegram (Mini App), уточним принцип работы: что происходит после клика на условный /start и как работает мини-приложение.

Когда разобрались с архитектурой и принципом работы мини-приложения, переходим к инструкции, как сделать 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 может быть и другой. Все зависит от конкретного проекта. Обратите внимание, что в файлы уже навешены стили на элементы (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