BotHost — полное руководство по Mini App

Что такое Mini App

Обзор технологии

Mini App (ранее известные как Web App) — это веб-приложения, которые запускаются прямо внутри Telegram и выглядят как нативная часть мессенджера. Они используют стандартные веб-технологии (HTML, CSS и JavaScript), но при этом имеют доступ к специальным API Telegram.

Рис. 1: Пример мини-приложения в Telegram

Ключевые особенности Mini App:

Быстрый доступ: Открываются через кнопку меню в боте, прямые ссылки или через кнопки в сообщениях
Адаптивный дизайн: Автоматически подстраиваются под светлую и темную тему Telegram
Доступ к данным: Могут получать информацию о пользователе (с его согласия)
Нативные элементы: Используют компоненты интерфейса Telegram, например MainButton
Безопасность: Работают только по HTTPS и имеют ограничения для безопасности пользователей

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

Преимущества использования BotHost

BotHost — это специализированная платформа для хостинга ботов и мини-приложений Telegram, которая существенно упрощает процесс их создания и поддержки:

Комплексное решение: Одна платформа для размещения как бота, так и мини-приложения
Автоматизация: Интеграция с GitHub для мгновенного обновления при изменении кода
SSL из коробки: Все домены автоматически получают HTTPS-сертификаты (обязательны для Mini App)
Домены: Возможность использовать поддомены bothost.ru или подключить свой домен
Мониторинг и логи: Удобный доступ к логам и статистике использования
Масштабирование: Простое увеличение ресурсов при росте нагрузки

Рис. 2: Интерфейс панели управления BotHost

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

Необходимые инструменты

Перед началом создания Mini App на BotHost, вам понадобятся:

Аккаунт BotHost: Зарегистрируйтесь на bothost.ru и выберите подходящий тарифный план
GitHub аккаунт: Репозиторий для хранения кода вашего приложения
Telegram бот: Созданный через @BotFather с полученным токеном
Базовые знания: HTML, CSS и JavaScript (минимальный уровень)
Редактор кода: VS Code, Sublime Text или любой другой текстовый редактор

Для локального тестирования (опционально):

Node.js: Версия 14.x или выше
Git: Для управления версиями кода

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

Первым шагом будет создание Telegram бота, через которого пользователи будут получать доступ к вашему мини-приложению:

Откройте @BotFather в Telegram
Отправьте команду /newbot
Введите название бота (может содержать любые символы)
Введите username бота (должен заканчиваться на "bot" и быть уникальным)
Получите и сохраните токен бота — он понадобится для настройки на BotHost

Рис. 3: Процесс создания бота через BotFather

⚠️ Никогда не публикуйте токен вашего бота в открытом доступе. Храните его в безопасном месте, так как он предоставляет полный доступ к управлению ботом.

Создание файлов

Структура проекта

Для корректной работы Mini App на BotHost важно правильно организовать структуру файлов. Вот рекомендуемая структура:

repository/
├── app.js           # Серверный код Node.js
├── package.json     # Настройки проекта
└── public/          # Папка с файлами мини-приложения
    ├── index.html   # Основной HTML файл
    ├── style.css    # Стили
    ├── script.js    # Клиентский JavaScript
    └── images/      # Папка для изображений

⚠️ Расположение файлов критически важно! HTML/CSS/JS файлы обязательно должны находиться в папке public, а не в корне репозитория.

Серверная часть (app.js)

Файл app.js в корне проекта отвечает за раздачу статических файлов из папки public. Вот готовый код сервера на Node.js:

// Сервер для раздачи статических файлов
const http = require('http');
const fs = require('fs');
const path = require('path');

const PORT = process.env.PORT || 3000;

const mimeTypes = {
  '.html': 'text/html',
  '.css': 'text/css',
  '.js': 'text/javascript',
  '.json': 'application/json',
  '.png': 'image/png',
  '.jpg': 'image/jpeg',
  '.gif': 'image/gif',
  '.ico': 'image/x-icon'
};

const server = http.createServer((req, res) => {
  console.log(`Запрос: ${req.method} ${req.url}`);
  
  let url = req.url;
  if (url === '/' || url === '') {
    url = '/index.html';
  }
  
  const filePath = path.join(__dirname, 'public', url);
  const extname = path.extname(filePath);
  const contentType = mimeTypes[extname] || 'text/plain';
  
  fs.readFile(filePath, (error, content) => {
    if (error) {
      if (error.code === 'ENOENT') {
        res.writeHead(404);
        res.end('Файл не найден');
      } else {
        res.writeHead(500);
        res.end(`Ошибка сервера: ${error.code}`);
      }
    } else {
      res.writeHead(200, { 'Content-Type': contentType });
      res.end(content, 'utf-8');
    }
  });
});

server.listen(PORT, '0.0.0.0', () => {
  console.log(`✅ Сервер запущен на порту ${PORT}`);
});

Этот код создает простой HTTP-сервер, который отдает файлы из папки public, определяя правильный Content-Type для разных типов файлов.

Настройка проекта (package.json)

Файл package.json содержит метаданные проекта и используется Node.js для управления зависимостями и скриптами:

{
  "name": "bothost-miniapp",
  "version": "1.0.0",
  "description": "Telegram Mini App на BotHost",
  "main": "app.js",
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon app.js"
  },
  "dependencies": {},
  "devDependencies": {
    "nodemon": "^2.0.20"
  }
}

Для простого статического мини-приложения нам не требуются внешние зависимости. nodemon добавлен как dev-зависимость для удобства локальной разработки.

HTML-страница (public/index.html)

Файл index.html — это основной файл вашего мини-приложения. Вот минимальный шаблон:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <title>Мое мини-приложение</title>
    
    <script src="https://telegram.org/js/telegram-web-app.js"></script>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="container">
        <header>
            <h1>Мое Mini App</h1>
            <p>Разработано на BotHost</p>
        </header>
        
        <main>
            <div class="card">
                <h2>Добро пожаловать!</h2>
                <p>Это ваше первое мини-приложение в Telegram.</p>
                <button id="mainButton" class="button">Нажмите меня</button>
            </div>
        </main>
    </div>
    
    <script src="script.js"></script>
</body>
</html>

⚠️ Скрипт telegram-web-app.js обязательно должен быть подключен в head документа для корректной работы с Telegram!

Стили (public/style.css)

Файл style.css содержит стили вашего мини-приложения. Вот базовый шаблон с поддержкой светлой и темной темы Telegram:

:root {
    --bg-color: #ffffff;
    --text-color: #1f2937;
    --hint-color: #6b7280;
    --button-color: #6366f1;
    --button-text-color: #ffffff;
    --card-bg: #f9fafb;
}

body {
    background-color: #ffffff;
    color: #1f2937;
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    margin: 0;
    padding: 0;
    font-size: 16px;
    line-height: 1.6;
}

.container {
    max-width: 450px;
    margin: 0 auto;
    padding: 20px 16px;
}

header {
    text-align: center;
    margin-bottom: 24px;
}

header h1 {
    margin-bottom: 8px;
    font-size: 24px;
    font-weight: 700;
    color: #6366f1;
}

header p {
    color: #6b7280;
    margin: 0;
}

.card {
    background-color: #f9fafb;
    border-radius: 12px;
    padding: 20px;
    margin-bottom: 16px;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
}

.card h2 {
    margin-top: 0;
    margin-bottom: 12px;
    font-size: 18px;
}

.button {
    background-color: #6366f1;
    color: #ffffff;
    border: none;
    border-radius: 8px;
    padding: 12px 20px;
    font-size: 15px;
    font-weight: 600;
    cursor: pointer;
    display: block;
    width: 100%;
    margin-top: 16px;
    transition: opacity 0.2s;
}

.button:active {
    opacity: 0.8;
}

JavaScript-логика (public/script.js)

Файл script.js содержит логику взаимодействия с Telegram API:

const tg = window.Telegram.WebApp;

tg.ready();

tg.expand();

document.addEventListener('DOMContentLoaded', function() {
    const mainButton = document.getElementById('mainButton');
    
    if (mainButton) {
        mainButton.addEventListener('click', function() {
            if (tg.HapticFeedback) {
                tg.HapticFeedback.impactOccurred('medium');
            }
            
            tg.MainButton.setText('ГОТОВО');
            tg.MainButton.show();
            
            tg.MainButton.onClick(function() {
                const data = {
                    action: 'button_pressed',
                    timestamp: new Date().toISOString()
                };
                
                tg.sendData(JSON.stringify(data));
                
                setTimeout(() => tg.close(), 1000);
            });
        });
    }
    
    if (tg.initDataUnsafe.user) {
        const user = tg.initDataUnsafe.user;
        console.log('Пользователь:', user.first_name, user.last_name);
    }
});

console.log('Mini App загружена!');
console.log('Текущая тема:', tg.colorScheme);

Этот базовый скрипт инициализирует мини-приложение, показывает как использовать MainButton и отправлять данные в бота.

Загрузка на GitHub

Создание репозитория

GitHub будет использоваться как хранилище для исходного кода и для автоматической интеграции с BotHost. Вот как создать и настроить репозиторий:

Зайдите на GitHub и авторизуйтесь
Нажмите кнопку "+" в правом верхнем углу и выберите "New repository"
Введите имя для репозитория (например, "telegram-miniapp")
Установите видимость "Public" (важно для работы с бесплатными тарифами BotHost)
Нажмите "Create repository"

После создания репозитория вы получите URL, который понадобится для интеграции с BotHost.

Загрузка файлов

Существует несколько способов загрузить файлы в репозиторий:

Способ 1: Через веб-интерфейс GitHub

В репозитории нажмите "Add file" → "Upload files" или "Create new file"
Создайте папку public (нажав "Create new file" и введя "public/file.txt" в имени файла)
Загрузите все файлы в соответствующие папки
Обязательно соблюдайте структуру: app.js и package.json в корне, остальные файлы внутри папки public

Рис. 4: Интерфейс загрузки файлов на GitHub

Способ 2: Через Git (рекомендуется)

# Клонируем пустой репозиторий
git clone https://github.com/username/telegram-miniapp.git
cd telegram-miniapp

# Создаем структуру папок
mkdir -p public/images

# Создаем файлы (или копируем их)
touch app.js package.json public/index.html public/style.css public/script.js

# Добавляем и коммитим изменения
git add .
git commit -m "Initial commit"
git push origin main

Проверка структуры

Перед интеграцией с BotHost важно убедиться, что файлы размещены правильно. Структура должна выглядеть следующим образом:

telegram-miniapp/
  ├── app.js
  ├── package.json
  └── public/
      ├── index.html
      ├── style.css
      └── script.js

Настройка на BotHost

Создание бота на платформе

После подготовки репозитория на GitHub, пора создать бот на BotHost:

Войдите в свой аккаунт на BotHost
Нажмите кнопку "Создать бота" или "Добавить бота"
Заполните форму создания бота:
- Название: Имя для внутренней идентификации
- Платформа: Telegram
- Библиотека/язык: Node.js
- Bot Token: Вставьте токен, полученный от BotFather
- Git URL репозитория: URL вашего GitHub репозитория
- Локация: Выберите ближайшую к вашим пользователям
Нажмите "Создать бота"

Рис. 5: Форма создания бота на платформе BotHost

Настройка домена

Для работы Mini App необходим HTTPS-домен. BotHost предлагает несколько вариантов:

Вариант 1: Поддомен на bothost.ru (базовый/платный тариф)

В панели управления ботом найдите поле для ввода домена
Введите желаемое имя (например, myapp)
В результате вы получите адрес вида https://myapp.bothost.ru

Вариант 2: Собственный домен (платный тариф)

Приобретите домен у любого регистратора
Настройте DNS-записи (A-запись указывающую на IP BotHost)
В панели управления введите свой домен
BotHost автоматически выпустит SSL-сертификат

Рис. 6: Настройка домена для мини-приложения на BotHost

⚠️ Telegram Mini App работает ТОЛЬКО по HTTPS! Убедитесь, что ваш домен имеет SSL-сертификат.

Конфигурация и запуск

После создания бота, BotHost автоматически клонирует ваш репозиторий и запускает приложение:

Перейдите в раздел "Console" или "Логи" для отслеживания процесса развертывания
Убедитесь, что установка зависимостей и запуск прошли успешно
Проверьте сообщение о запуске сервера на определенном порту

Если вы видите сообщение ✅ Сервер запущен на порту 3000 (или другой порт), значит все работает правильно.

Автоматическое обновление из GitHub

BotHost поддерживает автоматическое обновление при изменениях в репозитории:

В панели управления ботом найдите раздел "Автообновление"
Скопируйте предоставленный Webhook URL
В настройках GitHub репозитория:
- Перейдите в Settings → Webhooks → Add webhook
- Вставьте URL из BotHost
- Выберите формат "application/json"
- Нажмите "Add webhook"

Теперь при каждом push в репозиторий, BotHost автоматически обновит ваше приложение.

Интеграция с Telegram

Настройка кнопки Web App в меню бота

Чтобы пользователи могли легко открыть ваше Mini App из меню бота, настройте кнопку в BotFather:

Откройте @BotFather
Отправьте команду /mybots
Выберите вашего бота из списка
Нажмите "Bot Settings" → "Menu Button" или отправьте /setmenubutton
Введите текст для кнопки (например, "Открыть приложение")
Введите URL вашего приложения (например, https://myapp.bothost.ru)

Рис. 7: Настройка кнопки меню Mini App в BotFather

После этого в меню бота появится кнопка, при нажатии на которую будет открываться ваше Mini App.

Кнопка Web App в сообщениях

Вы также можете отправлять кнопки, открывающие Mini App, прямо в сообщениях бота.

Пример JavaScript-кода для бота на Node.js:

// Пример с использованием node-telegram-bot-api
const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot('YOUR_TOKEN', {polling: true});

bot.onText(/\/start/, (msg) => {
  const chatId = msg.chat.id;
  
  bot.sendMessage(chatId, 'Привет! Нажмите на кнопку, чтобы открыть мини-приложение:', {
    reply_markup: {
      inline_keyboard: [
        [{
          text: 'Открыть приложение',
          web_app: {url: 'https://myapp.bothost.ru'}
        }]
      ]
    }
  });
});

Такой код отправляет сообщение с кнопкой, которая открывает ваше мини-приложение при нажатии.

Получение данных из Mini App

Mini App может отправлять данные обратно в бота с помощью метода sendData(). Вот как это работает:

1. Отправка данных из Mini App:

// В script.js мини-приложения
const tg = window.Telegram.WebApp;

// Отправка данных в бота
function sendFormData() {
  const data = {
    name: document.getElementById('name').value,
    email: document.getElementById('email').value,
    feedback: document.getElementById('feedback').value
  };
  
  tg.sendData(JSON.stringify(data));
  
  tg.close();
}

2. Обработка данных в боте:

// В коде бота
bot.on('web_app_data', (msg) => {
  const chatId = msg.chat.id;
  const data = JSON.parse(msg.web_app_data.data);
  
  bot.sendMessage(chatId, 
    `Спасибо за отправку формы!\n\nИмя: ${data.name}\nEmail: ${data.email}\nОтзыв: ${data.feedback}`
  );
});

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

Продвинутые функции

Адаптация под темы Telegram

Telegram имеет светлую и темную темы, и ваше Mini App должно корректно адаптироваться под обе:

/* Автоматическая адаптация к теме Telegram */
:root {
  --my-background: var(--tg-theme-bg-color, #ffffff);
  --my-text: var(--tg-theme-text-color, #1f2937);
  --my-hint: var(--tg-theme-hint-color, #6b7280);
  --my-link: var(--tg-theme-link-color, #6366f1);
  --my-button: var(--tg-theme-button-color, #6366f1);
  --my-button-text: var(--tg-theme-button-text-color, #ffffff);
  --my-secondary-bg: var(--tg-theme-secondary-bg-color, #f9fafb);
}

body {
  background-color: var(--my-background);
  color: var(--my-text);
}

const tg = window.Telegram.WebApp;
const isDarkTheme = tg.colorScheme === 'dark';

if (isDarkTheme) {
}

Использование MainButton

MainButton — это нативный элемент интерфейса Telegram, который появляется внизу экрана:

const tg = window.Telegram.WebApp;

tg.MainButton.setText('ОТПРАВИТЬ');
tg.MainButton.setParams({
  color: '#6366f1',
  text_color: '#ffffff',
  is_active: true
});

tg.MainButton.show();

tg.MainButton.onClick(function() {
  sendData();
});

tg.MainButton.enable();

MainButton отлично подходит для основных действий в приложении, таких как отправка формы или переход к оплате.

Получение данных о пользователе

Mini App может получать базовую информацию о пользователе:

const tg = window.Telegram.WebApp;
const user = tg.initDataUnsafe.user;

if (user) {
  console.log('ID:', user.id);
  console.log('Имя:', user.first_name);
  console.log('Фамилия:', user.last_name);
  console.log('Юзернейм:', user.username);
  console.log('Язык:', user.language_code);
  
  document.getElementById('greeting').textContent = 
    `Привет, ${user.first_name}!`;
}

Эти данные можно использовать для персонализации интерфейса или для автозаполнения форм.

Haptic Feedback

На мобильных устройствах вы можете использовать тактильную обратную связь:

const tg = window.Telegram.WebApp;

if (tg.HapticFeedback) {
  tg.HapticFeedback.impactOccurred('light');
  tg.HapticFeedback.impactOccurred('medium');
  tg.HapticFeedback.impactOccurred('heavy');
  tg.HapticFeedback.notificationOccurred('success');
  tg.HapticFeedback.notificationOccurred('warning');
  tg.HapticFeedback.notificationOccurred('error');
}

Haptic Feedback делает взаимодействие с вашим приложением более естественным и приятным.

Решение проблем

Распространенные ошибки

При работе с Mini App на BotHost могут возникать следующие проблемы:

1. Ошибка "The web app was not found"

Причины:

Неверный URL вашего мини-приложения
Проблемы с DNS или SSL-сертификатом
Сервер не запущен или не отвечает

Решения:

Проверьте URL в браузере — он должен быть доступен
Убедитесь, что используется протокол HTTPS
Проверьте логи сервера на BotHost

2. Ошибка "White screen" (белый экран)

Причины:

Ошибка JavaScript в вашем приложении
Отсутствует скрипт telegram-web-app.js
Проблемы с CORS

Решения:

Проверьте консоль браузера на наличие ошибок
Убедитесь, что скрипт Telegram подключен в head
Проверьте структуру HTML

3. Проблемы с автообновлением из GitHub

Причины:

Неверно настроен webhook
Проблемы с правами доступа к репозиторию

Решения:

Проверьте настройки webhook в GitHub
Убедитесь, что репозиторий публичный
Проверьте логи webhook в GitHub

Отладка Mini App

Для отладки Mini App можно использовать несколько подходов:

1. Консоль разработчика

Откройте мини-приложение в браузере и используйте DevTools:

Chrome: F12 или Ctrl+Shift+I
Firefox: F12 или Ctrl+Shift+K
Safari: Option+Command+I

Вы можете просматривать логи, сетевые запросы и отлаживать JS.

2. Логи на BotHost

BotHost предоставляет доступ к логам сервера:

Перейдите в раздел "Console" или "Логи" в панели управления
Просмотрите вывод console.log из серверного кода
Отслеживайте ошибки сервера

3. Debug-режим

Добавьте отладочную информацию в свое приложение:

function createDebugPanel() {
  const debugPanel = document.createElement('div');
  debugPanel.id = 'debug-panel';
  debugPanel.style.position = 'fixed';
  debugPanel.style.bottom = '10px';
  debugPanel.style.left = '10px';
  debugPanel.style.background = 'rgba(0,0,0,0.8)';
  debugPanel.style.color = 'white';
  debugPanel.style.padding = '10px';
  debugPanel.style.borderRadius = '5px';
  debugPanel.style.fontSize = '12px';
  debugPanel.style.zIndex = '9999';
  
  const tg = window.Telegram.WebApp;
  debugPanel.innerHTML = `
    Версия WebApp: ${tg.version}
    Тема: ${tg.colorScheme}
    Платформа: ${tg.platform}
    Пользователь: ${tg.initDataUnsafe.user ? tg.initDataUnsafe.user.id : 'Нет'}
  `;
  
  document.body.appendChild(debugPanel);
}

🛠️

Нужна помощь?

Если вы столкнулись с проблемой, которую не можете решить самостоятельно, наш технический бот поддержки поможет вам разобраться!

Написать в поддержку

Содержание

Что такое Mini App

Обзор технологии

Преимущества использования BotHost

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

Необходимые инструменты

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

Создание файлов

Структура проекта

Серверная часть (app.js)

Настройка проекта (package.json)

HTML-страница (public/index.html)

Стили (public/style.css)

JavaScript-логика (public/script.js)

Загрузка на GitHub

Создание репозитория

Загрузка файлов

Способ 1: Через веб-интерфейс GitHub

Способ 2: Через Git (рекомендуется)

Проверка структуры

Настройка на BotHost

Создание бота на платформе

Настройка домена

Вариант 1: Поддомен на bothost.ru (базовый/платный тариф)

Вариант 2: Собственный домен (платный тариф)

Конфигурация и запуск

Автоматическое обновление из GitHub

Интеграция с Telegram

Настройка кнопки Web App в меню бота

Кнопка Web App в сообщениях

Получение данных из Mini App

1. Отправка данных из Mini App:

2. Обработка данных в боте:

Продвинутые функции

Адаптация под темы Telegram

Использование MainButton

Получение данных о пользователе

Haptic Feedback

Решение проблем

Распространенные ошибки

1. Ошибка "The web app was not found"

2. Ошибка "White screen" (белый экран)

3. Проблемы с автообновлением из GitHub

Отладка Mini App

1. Консоль разработчика

2. Логи на BotHost

3. Debug-режим

Нужна помощь?