Twitch → Telegram — уведомления о стримах

Старт, смена категории, скоро стрим или конец эфира — бот напишет туда, куда вы скажете. Настройка в Telegram.

Готовый бот: @twitch2telegram_bot

English: README.en.md

Главное меню	Типы оповещений
Шаблон + плейсхолдеры	🎲 Мне повезёт
Куда слать	Импорт из Twitch

Возможность	Как работает
Готовый бот	@twitch2telegram_bot — /start и меню
Языки	Русский и English — выбор при первом /start, смена в ⚙️ Настройки
Типы оповещений	Начало стрима · смена категории · предстоящий (Twitch schedule) · окончание стрима
Куда слать	Личка, канал, группа или сообщество (с темами)
Канал Twitch	Ссылка, m.twitch.tv или username
Текст	Шаблон с плейсхолдерами; примеры {username}, {game}, {name} — полный список
🎲 Мне повезёт	AI-шаблон одной кнопкой: Groq → Hugging Face → локальный пул (последние 100)
🎲 Что посмотреть?	Сохранённые фильтры на выбор, новый поиск, удаление как у подписок; категории → теги → зрители → язык → 18+
Картинка	Опционально к уведомлению — в начале или в конце подписи; превью ссылок тогда выкл
Отложенная отправка	Через N минут после старта, смены категории или после ухода офлайн (с перепроверкой Helix)
Заглушка повторов	Для старта стрима: не слать повторно X минут после первого уведомления
Напоминания по schedule	Если у стримера есть официальное расписание Twitch — напомнить за N минут
Подписки	Список, вкл/выкл, редактирование всех полей, удаление
Импорт из Twitch	OAuth → разово или синхронизация; только новые фолловы, ручные подписки не трогает
Расписание стримов	Мастер 📅 Создать расписание — текст на неделю для публикации
Системные оповещения	Вкл/выкл рассылок об обновлениях, доступности и прочих; падения Twitch (status.twitch.com)
Премиум	Stars-подписка или саб на Twitch-канал (PREMIUM_TWITCH_LOGIN) — больше активных алертов, sync, все типы оповещений
Партнёрка	Реферальная ссылка, 10% от Stars Premium приглашённых, заявки на вывод (вручную)
Админка	Рассылка в фоне (без подвисания) с типом в подписи, DeepL, статистика, обработка выводов, Демо режим
Команды	/start, /help, /cancel, /schedule, /feedback, /settings
Deploy	VPS (Docker)

Quick Start

1. Бот у @BotFather → TELEGRAM_BOT_TOKEN
2. Приложение на Twitch Developer Console → TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET (см. ниже)
3. cp .env.example .env — заполните переменные
4. docker compose up -d --build

Локально:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

Twitch API ключи

1. Twitch Developer Console → Register Your Application
2. OAuth Redirect URLs — https://<ваш-сервис>/oauth/twitch/callback (для импорта фолловов; локально — публичный HTTPS через ngrok/PUBLIC_BASE_URL)
3. Client ID → TWITCH_CLIENT_ID
4. New Secret → TWITCH_CLIENT_SECRET

Опрос стримов идёт через Client Credentials. Импорт подписок из Twitch — через user OAuth (user:read:follows).

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

При первом /start бот предложит выбрать язык (русский или English), затем покажет приветствие и главное меню.

Новая подписка

➕ Новая подписка — сначала тип оповещения:

Тип	Что делает
Начало стрима	Уведомление, когда канал выходит в эфир
Смена категории	Ловит старт стрима без оповещения; шлёт при каждой смене категории до конца стрима (без шага про повторы; Premium)
Предстоящий стрим	Напоминание за N минут, если у стримера есть Twitch schedule (без расписания — ошибка)
Окончание стрима	Уведомление, когда стрим завершился (тот же мастер, без шага про повторы)

Дальше мастер (для начала / смены категории / окончания стрима):

1. Канал Twitch (если оповещение уже есть — предложит редактор или продолжить)
2. Формат сообщения — свой текст или 🎲 Мне повезёт (AI)
3. Картинка (добавить / пропустить; при добавлении — позиция: в начале или в конце)
4. Игнорировать ключевые слова (опционально)
5. Превью ссылок (шаг пропускается, если есть картинка)
6. Отложить отправку (да/нет, минуты) — после старта, смены категории или после офлайна; перед отправкой Helix перепроверяется
7. Разрешить повторные уведомления (только для начала стрима; да/нет; при «нет» — минуты заглушки)
8. Куда слать: личка / канал / группа или сообщество
9. Для канала или группы — добавьте бота и подтвердите чат
10. Удалять предыдущие сообщения бота при новом оповещении? (да/нет; для смены категории по умолчанию только свои; если есть другие подписки на того же стримера в тот же чат — спросит, удалять ли и их)

Для предстоящего стрима после канала и проверки schedule — шаблон и настройки, затем минуты напоминания и куда слать (без отдельного вопроса «нужны ли напоминания»).

На каждом шаге доступны « Назад, Отмена и Главное меню. При редактировании подписки — только эти три кнопки.

Шаблон сообщения — в мастере показаны примеры {username}, {game}, {name}. Полный список плейсхолдеров (в т.ч. started_at, viewer_count, thumbnail_url, tags, …): PUBLIC_BASE_URL/placeholders (прод: https://bot.themarfa.name).

🎲 Мне повезёт — генерирует шаблон с плейсхолдерами. Цепочка: Groq (если задан ключ) → при сбое Hugging Face → если оба недоступны, случайный шаблон из локального пула в БД (до 100 последних удачных генераций на язык). В блоке «Пример» подставляются случайная игра из IGDB (те же Twitch API-ключи) и название стрима на её основе. После превью: продолжить, ещё раз, или полный мастер.

Группа или сообщество — отправьте:

• ссылку на тему: https://t.me/c/название/30
• @username группы
• ID группы (-100…)
• пересланное сообщение из группы («Переслано из: …»)

Права бота в группе: отправка сообщений (админ не обязателен). Нужно право удалять свои сообщения.

После настройки бот пришлёт «✅ Настройка завершена!» в личку и тестовое сообщение в выбранный чат.

Что посмотреть?

🎲 Что посмотреть? — подбор случайных live-стримов по вашим фильтрам (доступно всем, без Premium).

Если есть сохранённые фильтры, бот предложит:

Действие	Как
Выбрать фильтр	Нажать на имя → сразу несколько стримов
Новый поиск	Мастер фильтров с нуля
Удалить фильтры	Отдельная кнопка → отметить нужные (как удаление подписок) → удалить выбранные

Мастер нового поиска:

1. Категории Twitch (до 5)
2. Теги стрима (опционально; стрим должен содержать все указанные)
3. Диапазон зрителей
4. Язык стрима (опционально)
5. Исключить 18+ или нет
6. Сохранить фильтр на потом (до 5) или только сейчас

После подборки: Ещё варианты / Фильтры / новый поиск.

Импорт из Twitch

⬇️ Импорт подписок из Twitch — OAuth на Twitch, затем выбор: одноразовый импорт или синхронизация:

• одноразовый — как раньше, токен не сохраняется;
• синхронизация — период в днях, refresh token хранится зашифрованно; раз в период добавляются новые фолловы (сразу включены) и удаляются отфолловленные импорты (ручные подписки не трогаются);
• при импорте оповещения создаются на паузе (DM себе); в Настройках — Синхронизация подписок (период / отключить).

В Twitch Console нужен Redirect URL: https://<сервис>/oauth/twitch/callback (см. PUBLIC_BASE_URL).

Расписание стримов

📅 Создать расписание — мастер для текста публикации на следующую неделю (с ближайшего понедельника по воскресенье):

1. Описание и пример формата
2. Подтверждение «Сформировать расписание?»
3. Для каждого дня: игра/название стрима и время (15:30)
4. Стрим не планируется — пропустить день
5. Со 2-го дня — Завершить создание расписания (на последнем дне кнопки нет)

Итог — готовый текст, например:

- 20 июля 15:30 Sovereign Syndicate
- 21 июля 18:00 Just Chatting

Даты и месяцы формируются на языке пользователя.

Меню и команды

Кнопка / команда	Действие
/start	Главное меню
/help	Справка
/cancel	Отменить текущий мастер
/schedule	Создать расписание
/feedback	Обратная связь
/settings	Настройки
➕ Новая подписка	Тип оповещения → мастер
⬇️ Импорт подписок из Twitch	OAuth → разово или синхронизация
📋 Управление подписками	Список, редактирование, удаление
🎲 Что посмотреть?	Выбор фильтра / новый поиск / удаление фильтров
📅 Создать расписание	Текст расписания на неделю
⚙️ Настройки	Премиум, sync, системные уведомления, язык, партнёрка
↳ ⭐ Премиум	Stars или бесплатно за саб на Twitch-канал
↳ 🤝 Партнёрка	Статистика, ссылка, вывод (≥ 500 Stars), свои заявки
↳ 🔔 Системные уведомления	Обновления, доступность (бот / Twitch status), sync
↳ 🌐 Выбор языка	Русский / English
⚙️ Админка	Рассылка, статистика, выводы, демо режим (только ADMIN_USER_IDS)
↳ 📣 Рассылка	«Обновления бота», «Доступность бота» или «Прочие», отложенная отправка; в конце текста — тип и подсказка отключить в настройках
↳ 💸 Выводы	Заявки партнёров: ✅ выплачено / ❌ отклонить (баланс возвращается)
↳ 📊 Статистика	Пользователи, подписки, языки, платный Premium
↳ 🎬 Демо режим	Вкл. из админки: меню как у free без Premium, демо-подписки; Админка скрыта, кнопка «Демо режим» остаётся в главном меню — повторное нажатие выходит и сбрасывает всё демо
🐛 Сообщить о проблеме	@immarfa или Issues

Партнёрская программа

В ⚙️ Настройки → 🤝 Партнёрка:

1. Получить ссылку — t.me/<бот>?start=ref_<ваш_id>
2. Приглашённый открывает ссылку → привязка реферера (один раз)
3. С каждой оплаты / продления Stars Premium у приглашённого начисляется 10% Stars на баланс партнёра
4. Запросить вывод — весь доступный баланс, если ≥ 500 Stars; админу уходит заявка с кнопками
5. Мои заявки — статусы: в ожидании / выплачено / отклонено

Комиссия только с Stars Premium (не с Twitch-саба и не с внешних донатов). Выплата Stars через Telegram API недоступна — админ переводит вручную и отмечает заявку в боте.

Еженедельный отчёт админам: новые пользователи + число плативших Stars за неделю.

Редактирование подписки — в том же порядке, что и при создании: шаблон, картинка, ключевые слова, превью ссылок (скрыто, если есть картинка), задержка, повторы (не для смены категории и окончания), напоминания по расписанию (если включали при создании), куда слать, удаление старых сообщений. Для смены категории при включённом удалении — отдельно «удалять и другие оповещения».

Пример шаблона уведомления:

{username} в эфире!
{name}
Категория: {game}

Деплой

VPS (автодеплой)

Репозиторий на сервере: /opt/twitch-telegram-bot (рядом лежит .env).

При пуше в main GitHub Actions по SSH делает git fetch + reset --hard origin/main, затем scripts/vps-deploy.sh: docker compose -f compose.vps.yml up -d --build, проверка /health, cron ночного pg-backup. Secrets: VPS_HOST, VPS_USER, VPS_SSH_KEY.

Ручной запуск: Actions → Deploy VPS → Run workflow.

В .env на VPS нужны POSTGRES_PASSWORD (Postgres из compose.vps.yml) и PUBLIC_BASE_URL для OAuth (например https://bot.themarfa.name).

Локально / Docker

DATABASE_URL не задавайте — используется SQLite (DATABASE_PATH, volume в compose.yml).

Переменные окружения

Переменная	Описание
TELEGRAM_BOT_TOKEN	Токен BotFather
TWITCH_CLIENT_ID	Twitch Client ID
TWITCH_CLIENT_SECRET	Twitch Client Secret
ADMIN_USER_IDS	Telegram user ID админов (через запятую)
CHECK_INTERVAL	Опрос Twitch, сек (по умолчанию 60)
POSTGRES_PASSWORD	Пароль Postgres на VPS (compose.vps.yml)
DATABASE_URL	PostgreSQL. Если не задан — SQLite (compose.vps.yml задаёт сам)
DATABASE_PATH	SQLite: локально data/bot.db, в Docker /data/bot.db
MAX_SUBSCRIPTIONS_PER_OWNER	Лимит подписок на пользователя (по умолчанию 25)
PREMIUM_FREE_ACTIVE_LIMIT	Сколько активных алертов без Premium (по умолчанию 5)
PREMIUM_STARS_AMOUNT	Цена Stars-подписки (по умолчанию 100)
PREMIUM_SUBSCRIPTION_PERIOD	Период Stars-подписки, сек (по умолчанию 2592000 ≈ 30 дней)
PREMIUM_TWITCH_LOGIN	Twitch-логин для бесплатного Premium за саб (по умолчанию marfapr)
REFERRAL_COMMISSION_PERCENT	Комиссия партнёра с Stars Premium, % (по умолчанию 10)
REFERRAL_WITHDRAW_MIN_STARS	Минимум для заявки на вывод, Stars (по умолчанию 500)
PUBLIC_BASE_URL	Публичный HTTPS origin: OAuth (…/oauth/twitch/callback) и список плейсхолдеров (…/placeholders). Прод: https://bot.themarfa.name
TOKEN_ENCRYPTION_KEY	Опционально: Fernet-ключ для refresh token (иначе из TELEGRAM_BOT_TOKEN)
PORT	Порт health/OAuth (по умолчанию 8080)
DEEPL_API_KEY	DeepL — авто-перевод админ-рассылок на язык получателя
GROQ_API_KEY	Groq — основной LLM для Мне повезёт (алиасы: GROQ_API, GROK_API)
GROQ_TEXT_MODEL	Модель Groq (по умолчанию llama-3.1-8b-instant)
HF_TOKEN	Hugging Face — запасной LLM (алиас: HUGGING_FACE_API)
HF_TEXT_MODEL	Модель HF (по умолчанию Qwen/Qwen2.5-7B-Instruct)

Без ключей Groq/HF кнопка Мне повезёт всё равно работает — из локального пула шаблонов в БД.

Архитектура

Модуль	Назначение
bot.py	Wizard, меню, уведомления, «Что посмотреть?», админ-рассылка, Twitch Status, партнёрка, расписание
i18n.py	Тексты и клавиатуры (ru/en)
premium.py / premium_handlers.py	Premium (Stars / Twitch), реферальные начисления
demo_mode.py	Флаг админского демо-режима (free UX + сброс демо-подписок)
hf_text.py	AI-шаблоны: Groq → HF → локальный пул
twitch.py	Helix API, discovery live-стримов, шаблоны, status.twitch.com
translate.py	DeepL для админ-рассылок
links.py	Парсинг t.me/c/…/тема
health.py	/health, /placeholders, Twitch OAuth callback
db.py	SQLite или PostgreSQL, пул lucky_templates, watch-фильтры, рефералы

Опрос Twitch Helix ~60 сек, Statuspage ~120 сек, polling Telegram, без публичного webhook.

Заимствования

Изучены twitchrise, lajujabot, twitch-telegram-bot. Их код не копировался — только идеи (polling API, подписки, отправка в канал/группу).

Лицензия

Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)

См. LICENSE · https://creativecommons.org/licenses/by-nc-sa/4.0/

---

Код подготовлен с помощью Cursor

Поддержка проекта: Донат · Донат криптой · Telegram Tribute