Telegram-бот для проведения розыгрышей и конкурсов (Aiogram 3, SQLAlchemy, APScheduler)
- Python 99.4%
- Dockerfile 0.3%
- Batchfile 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| assets | ||
| bot | ||
| tests | ||
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| main.py | ||
| README.md | ||
| requirements.txt | ||
| run.bat | ||
🎁 Telegram Giveaway Bot (Бот для проведения розыгрышей)
Мощный, гибкий и надежный Telegram-бот для проведения розыгрышей и конкурсов, написанный на Python 3.12, Aiogram 3, SQLAlchemy 2.0 и APScheduler.
✨ Возможности
🛠 Панель администратора (/admin):
- Пошаговое создание розыгрыша:
- Название и подробное описание (поддержка HTML-форматирования: жирный, курсив, ссылки, эмодзи).
- Прикрепление медиа (фото или видео).
- Настраиваемый текст на кнопке участия (по умолчанию:
🎉 Участвовать). - Выбор количества призовых мест (1, 2, 3... N).
- Обязательная подписка на каналы спонсоров:
- Подключение любого количества каналов (открытых и закрытых).
- Быстрое добавление: пересылка любого поста из канала боту или отправка
@username. - Гибкое условие проверки:
- 📌 Подписка на ВСЕ указанные каналы (участник должен быть подписан на каждый).
- 🔀 Подписка хотя бы на ОДИН канал из списка (достаточно подписки на любой 1 из указанных спонсоров).
- Гибкая настройка даты и времени окончания:
- Быстрые шаблоны: 1 час, 6 часов, 24 часа, 3 дня, 7 дней.
- Без таймера (ручное завершение в любой момент).
- Точная дата и время окончания (по МСК / UTC).
👥 Управление участниками:
- Просмотр всех участников розыгрыша с пагинацией.
- Поиск участника по Telegram ID или @username.
- Просмотр детального профиля участника.
- Дисквалификация / Исключение: запрет на победу и участие конкретному пользователю.
- Выгрузка в CSV: экспорт полного списка участников с ID, именами, датой регистрации и статусом в один клик.
🎯 Ручной и автоматический выбор победителей:
- 🎲 Честный рандом: случайный выбор среди всех допущенных участников.
- 👤 Ручной выбор победителя:
- Выбор конкретного человека из интерактивного списка участников прямо в админке.
- Или ввод Telegram ID / @username вручную.
- ⭐ Скрытый / Гарантированный победитель:
- Возможность заранее отметить одного или нескольких участников как "тайных победителей". При подведении итогов система отдаст приоритет им (если они участвуют).
- 🔄 Перевыбор (Reroll):
- Возможность перевыбрать победителей в уже завершенном розыгрыше (случайно или вручную).
📢 Публикация и результаты:
- Предпросмотр поста в админке.
- Удобная пересылка готового сообщения с кнопкой участия в каналы и группы.
- Автоматическое обновление поста в канале после подведения итогов (публикация победителей с кликабельными ссылками).
- Личные уведомления победителям в ЛС от бота.
- Массовая рассылка сообщений всем пользователям бота из админки.
🚀 Установка и запуск
1. Клонирование и настройка виртуального окружения
python -m venv .venv
# Для Windows:
.venv\Scripts\activate
# Для Linux/macOS:
source .venv/bin/activate
2. Установка зависимостей
pip install -r requirements.txt
3. Конфигурация (.env)
Создайте файл .env в корневой папке проекта на основе .env.example:
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
ADMIN_IDS=123456789,987654321
DATABASE_URL=sqlite+aiosqlite:///data/giveaways.db
TIMEZONE=Europe/Moscow
BOT_TOKEN: токен, полученный у @BotFather.ADMIN_IDS: список Telegram ID администраторов через запятую (свой ID можно узнать в @userinfobot).
4. Запуск бота
python main.py
📌 Инструкция по добавлению каналов спонсоров
Чтобы бот мог проверять подписку пользователей на спонсорские каналы:
- Добавьте бота в канал/чат в качестве Администратора (достаточно базовых прав администратора).
- При создании розыгрыша укажите
@usernameканала (например,@my_channel).