# BotHost Mini App — Полное руководство
*Источник: [https://manual.bothost.ru/](https://manual.bothost.ru/)*
---
## Содержание
1. [Что такое Mini App](#что-такое-mini-app)
2. [Подготовка к работе](#подготовка-к-работе)
3. [Создание файлов](#создание-файлов)
4. [Загрузка на GitHub](#загрузка-на-github)
5. [Настройка на BotHost](#настройка-на-bothost)
6. [Интеграция с Telegram](#интеграция-с-telegram)
7. [Продвинутые функции](#продвинутые-функции)
8. [Решение проблем](#решение-проблем)
9. [Примеры проектов](#примеры-проектов)
---
## Что такое Mini App
### Обзор технологии
Mini App (ранее известные как Web App) — это веб-приложения, которые запускаются прямо внутри Telegram и выглядят как нативная часть мессенджера. Они используют стандартные веб-технологии (HTML, CSS и JavaScript), но при этом имеют доступ к специальным API Telegram.
Ключевые особенности Mini App:
* **Быстрый доступ:** Открываются через кнопку меню в боте, прямые ссылки или через кнопки в сообщениях
* **Адаптивный дизайн:** Автоматически подстраиваются под светлую и темную тему Telegram
* **Доступ к данным:** Могут получать информацию о пользователе (с его согласия)
* **Нативные элементы:** Используют компоненты интерфейса Telegram, например MainButton
* **Безопасность:** Работают только по HTTPS и имеют ограничения для безопасности пользователей
Mini App могут использоваться для множества сценариев: магазины, формы опросов, игры, дашборды, редакторы, каталоги и многое другое.
### Преимущества использования BotHost
BotHost — это специализированная платформа для хостинга ботов и мини-приложений Telegram, которая существенно упрощает процесс их создания и поддержки:
* **Комплексное решение:** Одна платформа для размещения как бота, так и мини-приложения
* **Автоматизация:** Интеграция с GitHub для мгновенного обновления при изменении кода
* **SSL из коробки:** Все домены автоматически получают HTTPS-сертификаты (обязательны для Mini App)
* **Домены:** Возможность использовать поддомены bothost.ru или подключить свой домен
* **Мониторинг и логи:** Удобный доступ к логам и статистике использования
* **Масштабирование:** Простое увеличение ресурсов при росте нагрузки
---
## Подготовка к работе
### Необходимые инструменты
Перед началом создания Mini App на BotHost, вам понадобятся:
* **Аккаунт BotHost:** Зарегистрируйтесь на [bothost.ru](https://bothost.ru/) и выберите подходящий тарифный план
* **GitHub аккаунт:** Репозиторий для хранения кода вашего приложения
* **Telegram бот:** Созданный через @BotFather с полученным токеном
* **Базовые знания:** HTML, CSS и JavaScript (минимальный уровень)
* **Редактор кода:** VS Code, Sublime Text или любой другой текстовый редактор
Для локального тестирования (опционально):
* **Node.js:** Версия 18.x или выше (рекомендуется LTS)
* **Git:** Для управления версиями кода
### Создание бота в Telegram
Первым шагом будет создание Telegram бота, через который пользователи будут получать доступ к вашему мини-приложению:
1. Откройте [@BotFather](https://t.me/BotFather) в Telegram
2. Отправьте команду `/newbot`
3. Введите **название** бота (может содержать любые символы)
4. Введите **username** бота (должен заканчиваться на "bot" и быть уникальным)
5. Получите и сохраните **токен** бота — он понадобится для настройки на BotHost
> ⚠️ **Важно:** Никогда не публикуйте токен вашего бота в открытом доступе. Храните его в безопасном месте, так как он предоставляет полный доступ к управлению ботом.
---
## Создание файлов
### Структура проекта
Для корректной работы 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:
```javascript
// Сервер для раздачи статических файлов
const http = require('http');
const fs = require('fs');
const path = require('path');
// Порт из переменных окружения BotHost или 3000 по умолчанию
const PORT = process.env.PORT || 3000;
// MIME-типы для разных файлов
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'
};
// Создаем HTTP-сервер
const server = http.createServer((req, res) => {
console.log(`Запрос: ${req.method} ${req.url}`);
// Нормализуем URL (убираем query string, убираем ведущие слэши для безопасного join)
let url = (req.url || '/').split('?')[0].replace(/^\/+/, '') || 'index.html';
// Определяем путь к файлу и проверяем, что он внутри public (защита от path traversal)
const publicDir = path.join(__dirname, 'public');
const filePath = path.join(publicDir, path.normalize(url));
const resolvedPath = path.resolve(filePath);
const resolvedPublic = path.resolve(publicDir);
if (!resolvedPath.startsWith(resolvedPublic + path.sep) && resolvedPath !== resolvedPublic) {
res.writeHead(403);
res.end('Доступ запрещён');
return;
}
const extname = path.extname(resolvedPath);
const contentType = mimeTypes[extname] || 'text/plain';
// Читаем файл
fs.readFile(resolvedPath, (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)
```json
{
"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)
```html
Мое мини-приложение