Разработка Telegram Mini App с нуля

Иван Корнев·21.05.2024·⏱4 мин

Чтобы создать Telegram Mini App, необходимо зарегистрировать бота через @BotFather, получить токен, разработать веб-интерфейс (фронтенд) и подключить его к боту через метод setMenuButton или прямую ссылку t.me/your_bot/appname. Весь процесс занимает от нескольких часов до пары дней в зависимости от сложности функционала.

Telegram Mini Apps (TMA) — это веб-приложения, которые открываются прямо внутри мессенджера. Они позволяют выводить сложный интерфейс, формы оплаты, каталоги товаров и интерактивные сервисы, не заставляя пользователя покидать чат. В отличие от обычных текстовых ботов, Mini App дают полный контроль над UI/UX.

Отличия Mini App от обычного бота

Понимание разницы критично для выбора архитектуры проекта. Обычный бот ограничен интерфейсом чата: кнопки под сообщением, списки выбора и текст. Mini App открывает полноценное окно браузера внутри Telegram.

Характеристика	Обычный бот	Telegram Mini App
Интерфейс	Текстовые сообщения, Inline-кнопки	Полноценный веб-сайт (HTML/CSS/JS)
Взаимодействие	Пошаговое (вопрос-ответ)	Одновременное отображение элементов
Дизайн	Стандартный стиль Telegram	Кастомный дизайн, анимации, графика
Сложность ввода	Ограничена клавиатурой	Любые формы, калькуляторы, карты
Идеально для	Уведомления, простая поддержка	Магазины, игры, сложные сервисы, крипто-кошельки

Главное преимущество: Пользователю не нужно скачивать отдельное приложение из стора. Он переходит по ссылке в боте и сразу начинает пользоваться сервисом.

Подготовка окружения и регистрация бота

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

Создание бота. Найдите в поиске Telegram официального бота @BotFather.
Команда создания. Отправьте команду /newbot.
Настройка имени. Придумайте название (отображается в списке чатов) и юзернейм (должен заканчиваться на bot, например MySuperApp_bot).
Получение токена. BotFather выдаст уникальный токен доступа (выглядит как набор символов). Сохраните его — он нужен для связи сервера с Telegram.

Для разработки самого приложения выберите стек технологий. Самый популярный и простой вариант:

Фронтенд: HTML, CSS, JavaScript (можно использовать React, Vue или Vite).
Бэкенд: Node.js, Python (Aiogram/FastAPI) или Go.
Хостинг: Любой сервис, поддерживающий HTTPS (Vercel, Netlify, Heroku или свой VPS).

Требование безопасности: Ваше мини-приложение должно работать строго по протоколу HTTPS. Telegram не позволит открыть сайт на незащищенном соединении.

Архитектура и подключение Web Apps

Telegram Mini App состоит из двух частей: бота (который инициирует запуск) и веб-страницы (которая отображает контент). Связующим звеном является скрипт telegram-web-app.js.

Шаг 1: Базовая верстка

Создайте файл index.html. В секцию <head> обязательно добавьте скрипт от Telegram:

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Этот скрипт дает доступ к объекту window.Telegram.WebApp, через который можно получать данные пользователя, менять цвета темы и управлять кнопками.

Шаг 2: Инициализация приложения

В вашем JavaScript файле инициализируйте приложение:

const tg = window.Telegram.WebApp;
tg.expand(); // Раскрывает приложение на всю высоту

Теперь вы можете обращаться к данным: tg.initDataUnsafe.user содержит информацию о пользователе (ID, имя, язык), если он запустил приложение из Telegram.

Шаг 3: Привязка к боту

Вернитесь в @BotFather. Используйте команду /newapp для создания привязки или настройте кнопку меню:

Выберите своего бота.
Нажмите Menu Button Setup.
Отправьте ссылку на ваше веб-приложение (например, https://myapp.vercel.app).
Задайте название кнопки (например, "Открыть магазин").

Теперь у пользователей слева от поля ввода текста появится кнопка, запускающая ваше приложение.

Интеграция дизайна и нативных функций

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

Пример использования цветов в CSS:

body {
    background-color: var(--tg-theme-bg-color);
    color: var(--tg-theme-text-color);
}
.button {
    background-color: var(--tg-theme-button-color);
    color: var(--tg-theme-button-text-color);
}

Также вы можете управлять главной кнопкой (Main Button) внизу экрана. Она идеально подходит для действий «Купить», «Отправить» или «Далее».

// Показать главную кнопку
tg.MainButton.setText("Оформить заказ");
tg.MainButton.show();

// Обработка нажатия
tg.MainButton.onClick(function() {
    tg.sendData("order_confirmed"); // Отправляет данные обратно боту
});

Совет по UX: Всегда тестируйте приложение на реальном мобильном устройстве. Эмуляторы в браузере не всегда корректно отображают поведение клавиатуры и скролла внутри Telegram.

Частые ошибки при разработке

Игнорирование мобильных устройств. Интерфейс делается только под десктоп, а 95% трафика в Telegram — мобильный. Используйте адаптивную верстку.
Отсутствие обработки загрузки. Веб-приложение может грузиться пару секунд. Обязательно добавьте прелоадер (экран загрузки), иначе пользователь увидит белый экран и закроет окно.
Некорректная работа с данными. Попытка использовать initData без проверки хеша на бэкенде. Злоумышленники могут подделать данные пользователя. Всегда валидируйте initData на сервере с помощью токена бота.
Блокировка сторонних ресурсов. Некоторые сети или прокси могут блокировать внешние скрипты. Старайтесь минимизировать зависимости.

FAQ

Можно ли принимать оплату внутри Mini App? Да, Telegram поддерживает нативные платежи. Вы можете использовать Invoice API бота для выставления счетов прямо внутри интерфейса мини-приложения.

Нужно ли модерировать приложение перед публикацией? Для базовой работы через кнопку меню модерация не требуется. Однако, если вы хотите добавить приложение в каталог Telegram или использовать определенные функции продвижения, может потребоваться проверка со стороны команды Telegram.

Какие ограничения по размеру приложения? Само приложение хранится на вашем хостинге, поэтому ограничение только в скорости загрузки. Рекомендуется, чтобы вес первой страницы не превышал 1-2 МБ для быстрой работы на мобильных сетях.

Работает ли Mini App без интернета? Нет, так как это веб-технология. Требуется постоянное соединение для загрузки контента и обмена данными с сервером.