Hiddify Telegram Bot

Telegram бот для управления подписками Hiddify VPN с автоматизацией платежей, учётом трафика и уведомлением пользователей.

🚀 Возможности

• Автоматическая регистрация — создание пользователей в Hiddify при оплате
• Управление подписками — продление, сброс трафика, проверка статуса
• Платежи через админа — пользователь отправляет чек, админ подтверждает
• Мониторинг трафика — отображение использованного и доступного лимита
• Уведомления — напоминание об истечении подписки (за 1 и 4 дня)
• Рассылки — массовая рассылка сообщений всем пользователям
• Кэширование — быстрый отклик бота благодаря кэшированию данных (30 сек)

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

hiddify/
├── main.py                 # Точка входа, запуск бота
├── config.py               # Конфигурация (токены, настройки API)
├── database.py             # Работа с SQLite базой данных
├── hiddify_api.py          # Клиент для Hiddify API
├── requirements.txt        # Зависимости Python
│
├── handlers/               # Обработчики сообщений и команд
│   ├── __init__.py
│   ├── commands.py         # Команды /start, /msg_all
│   ├── callbacks.py        # Callback query (кнопки)
│   ├── messages.py         # Текстовые сообщения, медиа
│   └── admin.py            # Админские обработчики
│
├── services/               # Бизнес-логика
│   ├── __init__.py
│   ├── hiddify_service.py  # Обёртка над Hiddify API + кэш
│   ├── user_service.py     # Управление пользователями
│   ├── payment_service.py  # Платежи и баланс
│   ├── subscription_service.py # Подписки и сброс трафика
│   └── notification_service.py # Уведомления и рассылки
│
└── keyboards/              # Inline-клавиатуры
    ├── __init__.py
    ├── main_menu.py        # Главное меню
    ├── subscription.py     # Выбор тарифа
    ├── payment.py          # Платежи
    ├── profile.py          # Профиль пользователя
    └── admin.py            # Админские кнопки

⚙️ Установка

1. Клонирование репозитория

git clone https://github.com/prasx/hiddify-tg-bot
cd hiddify

2. Создание виртуального окружения

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv .venv
source .venv/bin/activate

3. Установка зависимостей

pip install -r requirements.txt

4. Настройка конфигурации

Откройте файл config.py и заполните настройки:

class BotConfig:
    """Конфигурация Telegram бота"""
    ADMIN_PAYMENTS = 31869384  # Telegram ID администратора
    TOKEN = "YOUR_BOT_TOKEN"   # Токен бота от @BotFather


class HiddifyConfig:
    """Конфигурация Hiddify API и сервера"""
    BASE_URL = "https://your-hiddify-domain.com"
    ADMIN_PATH = "/your-admin-path"
    USER_PATH = "/your-user-path"
    API_KEY = "your-api-key"  # Ключ API из панели Hiddify

5. Настройка тарифов

В config.py измените тарифы под себя:

class TariffConfig:
    """Тарифные планы"""
    TARIFFS = {
        "30day": {"package_days": 30, "usage_limit_GB": 130, "price": 400, "emoji": "🤏"},
        "60day": {"package_days": 60, "usage_limit_GB": 370, "price": 800, "emoji": "👍"},
        "90day": {"package_days": 90, "usage_limit_GB": 690, "price": 1200, "emoji": "🤘"},
    }

🎯 Запуск бота

python main.py

После запуска бот:

1. Инициализирует базу данных users.db
2. Подключится к Hiddify API
3. Запустит фоновую задачу уведомлений
4. Начнёт обрабатывать сообщения

📋 Команды

Пользовательские

• /start — Запустить бота, показать главную меню
• Кнопки меню:
  • 🔗 Получить профиль — ссылка на подписку (Hiddify/V2Ray)
  • 💵 Пополнить баланс — выбор тарифа и оплата
  • 🔄 Обновить подписку — продление при достаточном балансе
  • 📱 Установить App — ссылки на приложения

Администраторские

• /msg_all <сообщение> — Рассылка сообщения всем пользователям

Только для ADMIN_PAYMENTS:

• Просмотр списка пользователей
• Подтверждение платежей
• Ручное пополнение баланса

🗄️ База данных

Бот использует SQLite (users.db) с двумя таблицами:

users

Поле	Тип	Описание
id	INTEGER	Первичный ключ
user_id	INTEGER	Telegram ID пользователя
uuid	TEXT	UUID в Hiddify
profile	TEXT	JSON с данными (баланс, тариф, etc.)
pos	TEXT	Текущая позиция в меню

admins

Поле	Тип	Описание
admin_id	INTEGER	Первичный ключ
tg_id	INTEGER	Telegram ID администратора

🔧 Настройка Hiddify

1. Получение API ключа

1. Откройте панель администратора Hiddify
2. Перейдите в настройки API
3. Создайте новый API ключ
4. Скопируйте ключ в config.py

2. Получение путей

• ADMIN_PATH — путь к админ-панели (например, /admin-link)
• USER_PATH — путь для пользовательских ссылок (например, /user-link)

📊 Логирование

Бот использует логирование с уровнем INFO:

2026-02-26 14:30:00,123 - root - INFO - Бот запускается...
2026-02-26 14:30:01,456 - services.hiddify_service - INFO - HiddifyService инициализирован (кэш TTL: 30с)
2026-02-26 14:30:02,789 - root - INFO - Пользователь username (ID: 123456789) зарегистрирован.

Для отладки измените в main.py:

logging.basicConfig(level=logging.DEBUG, ...)

🚀 Производительность

Кэширование

• TTL кэша: 30 секунд (настраивается в HiddifyService)
• Механизм: In-memory кэш в экземпляре сервиса
• Эффект: Повторные запросы выполняются за ~1-5ms вместо ~500-1000ms

Оптимизация

• Все обработчики используют один экземпляр HiddifyService
• Кэш общий для всех запросов
• Автоматическая очистка устаревших записей

🔐 Безопасность

⚠️ Важно!

1. Не коммитьте токены в Git! Используйте .env или удалите config.py из репозитория
2. Ограничьте доступ к админ-панели Hiddify по IP
3. Регулярно обновляйте зависимости (pip install --upgrade -r requirements.txt)

Рекомендации

# Добавьте config.py в .gitignore
echo "config.py" >> .gitignore

# Или используйте переменные окружения
# TELEGRAM_BOT_TOKEN=your_token
# HIDDIFY_API_KEY=your_key

📦 Зависимости

Пакет	Версия	Назначение
aiogram	3.15.0	Асинхронный Telegram Bot API
requests	2.32.3	HTTP-запросы к Hiddify API

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

Бот не запускается

1. Проверьте токен бота в config.py
2. Убедитесь, что зависимости установлены: pip install -r requirements.txt
3. Проверьте логи на наличие ошибок

Ошибка подключения к Hiddify

1. Проверьте BASE_URL, ADMIN_PATH, API_KEY
2. Убедитесь, что сервер Hiddify доступен
3. Проверьте права доступа API ключа

Пользователь не получает подписку

1. Проверьте баланс пользователя
2. Убедитесь, что тариф выбран (ticket_tariff в профиле)
3. Проверьте логи создания пользователя в Hiddify

📈 Планы развития

• Добавить .env для секретов
• Интеграция с платёжными системами (ЮKassa, CryptoBot)
• Веб-интерфейс для администратора
• Статистика использования (графики, метрики)
• Реферальная система
• Промокоды и скидки

📝 Лицензия

MIT License — свободное использование ссылки проекта автора.

🙏 Благодарности

• Hiddify — отличная панель управления
• aiogram — лучший асинхронный фреймворк для Telegram ботов

---

Статус: ✅ Готово к использованию в продакшене

Последнее обновление: Февраль 2026