/::docs::about
   ____ _            _ _
  / ___| | __ _ _ __(_) |_ _   _
 | |   | |/ _` | '__| | __| | | |
 | |___| | (_| | |  | | |_| |_| |
  \____|_|\__,_|_|  |_|\__|\__, |
                           |___/

clarity.sys — what it is

Clarity is a chat-bot for Twitch and Kick rolled into one. A single bot account (shizick666 on Twitch, sh1zick on Kick) works on any channel where it is moderator.

Clarity — это чат-бот для Twitch и Kick в одном лице. Один аккаунт бота (shizick666 на Twitch, sh1zick на Kick) умеет работать на любом канале где он назначен модератором.

what it can doчто умеет

  • Faceit — live elo, stats for today, last match, lobby with live score
  • Stream — status, uptime, change title/category by command
  • Music recognition — !track identifies the song playing (Shazam-like via AudD)
  • Economy — coins for activity, transfers, leaderboards, daily bonuses
  • Trivia / mini-games — quizzes with auto-start, in-chat mini-games
  • Giveaways / lottery — raffles through the bot
  • Timers — recurring chat messages
  • Custom commands with templating ($(random), $(choose), $(urlfetch))
  • Auto-moderation — link and ban-word filters with timeout
  • Faceit — реальное эло, статистика за сегодня, последний матч, лобби с live score
  • Stream — статус, аптайм, изменение названия/категории через команду
  • Music recognition — !трек распознаёт играющий трек (Shazam-like через AudD)
  • Economy — монеты за активность, переводы, топ, ежедневные бонусы
  • Trivia / mini-games — викторины с автозапуском, мини-игры в чате
  • Giveaways / lottery — розыгрыши через бота
  • Timers — периодические сообщения в чат
  • Custom commands с шаблонизатором ($(random), $(choose), $(urlfetch))
  • Auto-moderation — фильтр ссылок и банвордов с таймаутом

tech stackтех-стек

runtime  :: python 3.12  + asyncio
web      :: quart (async flask)
twitch   :: twitchio (irc) + helix api
kick     :: kick public api v1 + webhooks
deploy   :: vps (ubuntu) :: systemd :: nginx
/::docs::connect bot

connect bot to your channel

1. open the dashboard1. зайти в дашборд

Go to claritysync.ru/login. Pick a provider — type 1 for Twitch or 2 for Kick. Confirm in OAuth — after the redirect you'll land on the dashboard.

Открой claritysync.ru/login. На странице выбери провайдер — введи 1 для twitch или 2 для kick. Подтверди в OAuth — после редиректа окажешься в дашборде.

2. make the bot a mod2. сделать бота модератором

Many features (timeouts, message deletion, Helix sending without cooldowns) require the bot to be a moderator of your channel.

Многие фичи (тайм-ауты, удаление сообщений, отправка через Helix без кулдаунов) требуют чтобы бот был модератором канала.

# in your own chatв чате своего канала
/mod shizick666     # for twitchдля twitch
/mod sh1zick        # for kickдля kick

3. connect the bot3. подключить бота

On the main dashboard click bot: offline → online. The bot will join your chat and start working.

В дашборде на главной нажми кнопку bot: offline → online. Бот зайдёт в твой чат и начнёт работать.

If you're an admin — you can switch between all channels where the bot is added via the dropdown at the top.

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

4. configure4. настроить

Open the settings tab:

Открой вкладку settings:

  • faceit nickname — for !elo, !today, !lobby
  • moderation — enable auto link/banword filter
  • economy — enable coins
  • trivia autostart — auto rounds every N minutes
  • faceit nickname — для !elo, !today, !lobby
  • moderation — включить авто-фильтр ссылок/банвордов
  • economy — включить монеты
  • trivia autostart — авто-раунды каждые N минут
/::docs::dashboard

dashboard tour

top bar

  • >_ — logo, link to main
  • target dropdown (admin) — switch between channels
  • lang / logout — language toggle and sign out
  • >_ — лого, ссылка на главную
  • выпадашка target (admin) — переключение между каналами
  • lang / logout — переключение языка и выход

tabs (dock at the bottom)tabs (dock внизу)

  • dashboard — embedded player + chat + quick actions
  • streamers (admin) — all channels with bot status, add/remove
  • modules — custom commands, faceit, economy, moderation
  • giveaway — raffle controls
  • timers — periodic messages
  • settings — all toggles and fields
  • dashboard — embedded player + чат + быстрые действия
  • streamers (admin) — список всех каналов с бот-статусом, добавление/удаление
  • modules — кастомные команды, faceit, экономика, модерация
  • giveaway — управление розыгрышем
  • timers — периодические сообщения
  • settings — все тоглы и поля настройки

status bar (bottom)status bar (снизу)

clarity@dashboard | target | mode | bot:live | up:⠋ 14m | last:31.05 22:14 | tip: ctrl+k
/::docs::shell & cmd+k

shell / cmd+k palette

command palette

Press Ctrl+K (or Cmd+K on Mac) anywhere — opens fuzzy-search over actions.

Нажми Ctrl+K (или Cmd+K на Mac) откуда угодно — откроется fuzzy-поиск по действиям.

Type to filter (e.g. str finds go: streamers). ↑↓ to navigate, Enter to execute, Esc to close.

Печатай — фильтруется список (например str найдёт go: streamers). ↑↓ навигация, Enter выполнить, Esc закрыть.

shell mode

In the palette type : — switches to shell mode. Available commands:

В палитре напечатай : — переходишь в режим shell. Доступны команды:

:help                    list shell commands
:whoami                  show current user / target / mode
:go <view>               jump to view (dashboard, modules, ...)
:bot on | off            toggle bot for current target
:lang                    toggle language
:target <name>           switch target channel (admin)
:cmd add !trig <text>    add custom command
:cmd del !trig           remove custom command
:streamer add <login>    whitelist new streamer (admin)
:streamer rm <login>     remove streamer (admin)
:logout / :reload / :clear

login shell (on the login page)login shell (на странице логина)

A working interactive shell on /login. You type:

На /login рабочий interactive shell. Вводишь:

  • 1 or twitch — auth via twitch
  • 2 or kick — auth via kick
  • about — open the about modal
  • help, whoami, clear, ls — standard shell set
  • 1 или twitch — auth via twitch
  • 2 или kick — auth via kick
  • about — открыть about-модалку
  • help, whoami, clear, ls — стандартный shell-набор

As soon as you type — autocomplete popup appears. Tab inserts a command, ↑↓ navigates history.

Когда напечатаешь любой символ — popup с автокомплитом. Tab вставляет команду, ↑↓ навигация по истории.

/::docs::commands::faceit

metrics.faceit // faceit stats

Requires a faceit nickname in channel settings. Supports CS2/CS:GO.

Требуют faceit ник в настройках канала. Поддержка CS2/CS:GO.

!elo !ело
current elo and smart-elo (with today's delta)текущее эло и smart-эло (с учётом дельты за сегодня)
!today !сегодня
today's stats: W/L, ± elo, starting eloстатистика за сегодня: W/L, +/- эло, стартовое эло
!last !последний
last match result (map, score, ±elo)результат последнего матча (карта, счёт, ±эло)
!lobby !лобби
live status of current match: map, score, time, avg team elolive-статус текущего матча: карта, счёт, время, средний эло команд
!faceit
link to faceit profileссылка на профиль faceit

how to set upкак настроить

Modules → faceit → enter your faceit nickname → save. Bot pulls data via official Faceit API + unofficial endpoints for lobby.

Modules → faceit → введи свой ник на faceit → сохрани. Бот тянет данные через официальный Faceit API + неофициальные эндпоинты для лобби.

/::docs::commands::stream

helix.controller // stream info + control

!stream !стрим !статистика
status: category, viewers, uptime, today's messagesстатус: категория, зрители, аптайм, сегодняшние сообщения
!title <text>
change stream titleизменить название стрима [mod]
!game <category>
change categoryизменить категорию [mod]
!cs / !cs2 / !кс / !кс2
quick switch to Counter-Strikeбыстрая смена на Counter-Strike [mod]
!jc / !афк / !общение
quick switch to Just Chattingбыстрая смена на Just Chatting [mod]
!dota / !дота
quick switch to Dota 2быстрая смена на Dota 2 [mod]

To change title/category the streamer must be logged into the dashboard (we need their user-token).

Для смены title/category нужно чтобы стример был залогинен в дашборд (нужен его user-token).

/::docs::commands::track

audio.fingerprint // shazam-like track recognition

Shazam-like: bot listens to stream audio and identifies the playing track.

Shazam-like: бот слушает аудио стрима и определяет играющий трек.

!track !трек !song !песня !music !shazam
identify the music playing right nowраспознать музыку играющую сейчас

how it worksкак работает

  1. Bot fetches HLS link to the stream via yt-dlp -g
  2. ffmpeg extracts 12 seconds of audio
  3. File is sent to AudD API for recognition
  4. Result is cached for 90 seconds — repeat !track from viewers doesn't hit the API unnecessarily
  5. Бот берёт HLS-ссылку на стрим через yt-dlp -g
  6. ffmpeg вытаскивает 12 секунд аудио
  7. Файл отправляется в AudD API для распознавания
  8. Результат кэшируется на 90 секунд — повторные !трек от зрителей не дёргают API лишний раз

possible responsesвозможные ответы

🎵 @user now playingсейчас играет: Artist — Title 🔗 https://song.link/...
🤷 @user No music detected (or track unknown).Музыки не слышно (или трек неизвестен).
🤷 @user Stream is offline.Стрим оффлайн.
/::docs::commands::economy

coin.ledger // economy: coins, balance, transfers

Channel virtual currency (coins/tugriks). Viewers earn by being active in chat.

Виртуальная валюта канала (монеты/тугрики). Зрители получают за активность в чате.

!balance !баланс
my balanceмой баланс
!me !я
my stats: messages, days in chat, rankмоя статистика: сообщения, дни в чате, ранг
!pay @user amount !перевод
transfer coins to another viewerперевести монеты другому зрителю
!rich !богачи !top
top-10 by balanceтоп-10 по балансу
!top !топ
top-10 by message countтоп-10 по количеству сообщений

how to set upкак настроить

Modules → economy → enable. You can configure rates (coins per message, sub bonus, etc.).

Modules → economy → включить. Можно настроить ставки (сколько монет за сообщение, бонус за сабскрайб и т.д.).

/::docs::commands::trivia

q.engine // quiz dispatcher

!trivia
start roundначать раунд [mod]
!trivia stop
stop roundостановить раунд [mod]

Bot asks a question — viewers write answers in chat. First correct one gets coins.

Бот задаёт вопрос — зрители пишут ответы в чат. Первый правильный получает монеты.

autostartавтозапуск

In settings you can enable trivia autostart — bot launches rounds every N minutes (e.g. 15-30 min).

В settings можно включить trivia autostart — бот сам запускает раунды каждые N минут (например, 15-30 мин).

/::docs::commands::mini-games

entropy.lab // stochastic mini-games

Games tied to economy — stake coins, win or lose.

Игры с экономикой — ставишь монеты, выигрываешь или теряешь.

!dice <stake> !кости
dice roll — higher rolls wins, you vs botбросок костей — выпадет больше у тебя или у бота
!duel @user <stake> !дуэль
challenge another viewer to a duelвызвать другого зрителя на дуэль
!roulette <stake> <red|black|green> !рулетка
roulette with colorрусская рулетка с цветом

Full set of games and cooldowns — dashboard Modules → mini-games.

Полный набор игр и кулдауны — в дашборде Modules → mini-games.

/::docs::commands::giveaway

raffle.daemon + lottery.sampler // prize draws

giveaway

Keyword-based raffle. Streamer starts, bot collects participants, then picks a winner.

Розыгрыш с ключевым словом. Стример запускает, бот собирает участников, потом выбирает победителя.

+ (or your own keywordили своё слово)
enter the active raffleучаствовать в активном розыгрыше

Controls — dashboard giveaway tab:

Управление — в дашборде, вкладка giveaway:

  • set a keyword (e.g. +)
  • click start — bot announces in chat
  • real-time counter shows participants
  • click pick winner — bot picks a random one and writes in chat
  • задаёшь keyword (например +)
  • жмёшь start — бот объявляет в чат
  • счётчик в реальном времени показывает участников
  • жмёшь pick winner — бот выбирает случайного и пишет в чат

lottery

!lottery <stake> !лотерея
enter lotteryвойти в лотерею
!lottery start !лотерея старт
start roundначать раунд [mod]
/::docs::commands::timers

cron // periodic chat messages

Bot writes a given message to chat every N minutes. Useful for reminders (social media links, rules, etc.).

Бот раз в N минут пишет в чат заданное сообщение. Полезно для напоминаний (ссылки на соц-сети, правила, и т.д.).

how to set upкак настроить

Tab timers in the dashboard. Each timer has:

Вкладка timers в дашборде. Каждый таймер имеет:

  • interval — every how many minutes to send
  • message — what to send
  • you can create any number of timers per channel
  • interval — каждые сколько минут писать
  • message — что писать
  • можно создать сколько угодно таймеров на канал

The templating engine is supported inside timer messages.

Поддерживается шаблонизатор внутри сообщения таймера.

/::docs::commands::moderation

guard.engine // auto-moderation

Bot auto-timeouts viewers for violations. Requires mod rights on the channel.

Бот автоматически тайм-аутит зрителей за нарушения. Требует mod-права на канале.

link filterфильтр ссылок

When enabled — viewers without rights can't post links. Streamer, mods, VIPs and whitelisted users — can.

Когда включён — зрители без прав не могут писать ссылки. Стример, мод, вип, и whitelisted-пользователи — могут.

banword filterфильтр банвордов

List of forbidden words is configured in the dashboard. On trigger — timeout.

Список запрещённых слов настраивается в дашборде. При срабатывании — таймаут.

immunityиммунитет

Bot doesn't try to timeout mods and the streamer (Twitch would refuse anyway). These accounts get a joke reply in chat instead.

Бот не пытается тайм-аутить модов и стримера (Twitch всё равно бы отказал). Эти аккаунты получают шуточный ответ в чат вместо тайм-аута.

settingsнастройки

  • timeout duration — seconds
  • timeout message — what bot writes in chat
  • whitelist — who is allowed to post links
  • длительность таймаута — секунд
  • сообщение при таймауте — что бот пишет в чат
  • whitelist — кому можно писать ссылки
/::docs::commands::custom

directive.set // custom commands

Your own !commands with predefined responses.

Свои !команды с заданным ответом.

via chatчерез чат (mod)

!addcmd !trigger <response>
add commandдобавить команду
!editcmd !trigger <new response>
editизменить
!delcmd !trigger
deleteудалить

via dashboardчерез дашборд

Tab modules → custom commands. Add, edit, delete — changes apply instantly without bot restart.

Вкладка modules → раздел custom commands. Можно добавлять, редактировать, удалять — изменения применяются сразу без рестарта бота.

examplesпримеры

$ !addcmd !discord https://discord.gg/xxx
[ok] command !discord addedкоманда !discord добавлена

$ !discord
bot: https://discord.gg/xxx
/::docs::commands::templating

templating // dynamic substitutions

Inside a custom command response (and timer message) you can use templates. They are substituted on the fly.

Внутри ответа кастомной команды (и timer-сообщения) можно использовать шаблоны. Они подставляются на лету.

$(user)
name of who called the commandимя того кто вызвал команду
$(channel)
channel nameимя канала
$(touser)
name of who was mentioned (after @)имя того кого упомянули в команде (после @ )
$(random N M)
random number from N to Mслучайное число от N до M
$(choose a|b|c)
random choice from list separated by |случайный вариант из списка через |
$(urlfetch URL)
fetch text from URL and insert (for API integration)скачать текст по URL и вставить (для API)

examplesпримеры

$ !addcmd !hug $(user) hugs $(touser) 🤗
user:  !hug @viewer
bot:   user hugs viewer 🤗

$ !addcmd !dice rolled $(random 1 6) 🎲
bot:   rolled 4 🎲

$ !addcmd !shoot $(choose hit|missed|critical hit)
bot:   critical hit
$ !addcmd !hug $(user) обнимает $(touser) 🤗
user:  !hug @viewer
bot:   user обнимает viewer 🤗

$ !addcmd !dice выпало $(random 1 6) 🎲
bot:   выпало 4 🎲

$ !addcmd !shoot $(choose попал|промахнулся|критический хит)
bot:   критический хит
/::docs::studio tools::overlay.broadcast

overlay.broadcast // chat-overlays for OBS Browser Source

Ready-made HTML chat overlays for embedding in OBS. Connected as a Browser Source — separate layer on top of the scene. Support role-based colors (broadcaster / mod / vip / sub), badges, 7TV/BTTV/FFZ emotes, avatars and smooth fade-out of old messages.

Готовые HTML-оверлеи чата для встройки в OBS. Подключаются как Browser Source — отдельным слоем поверх сцены. Поддерживают цвета по ролям (broadcaster / mod / vip / sub), бейджи, 7TV/BTTV/FFZ эмодзи, аватарки и плавный fade-out старых сообщений.

how to connect in OBSкак подключить в OBS

  1. in the dashboard open the overlays tab
  2. pick a style you like, copy its URL
  3. in OBS: + → Browser → URL, paste the link, width 420, height 720 (or your size)
  4. checkbox Shutdown source when not visible — recommended (saves CPU)
  5. в дашборде открыть вкладку overlays
  6. выбрать понравившийся стиль из списка, скопировать его URL
  7. в OBS: + → Browser → URL, вставить ссылку, ширина 420, высота 720 (или под себя)
  8. галочка Shutdown source when not visible — рекомендуется (экономит CPU)

stylesстили

7 ready-made designs included — for different stream aesthetics:

В комплекте 7 готовых оформлений — для разной эстетики стрима:

  • cards — colored plates with avatar inside (name above, text below). The most "modern".
  • terminal — monochrome console style (different colors per role). Good for hacker/IT streams.
  • glass — semi-transparent cards with blur effect. Minimalism.
  • neon — neon glow and gradients. For bright scenes.
  • minimal — no frames, just colored nicks and text. Doesn't distract.
  • retro — pixel font + thick shadows. Vintage/retro games.
  • bubbles — big bubbles with avatar on the left (name+text in one line).
  • cards — цветные плашки с аватаркой внутри (имя сверху, текст ниже). Самый «современный».
  • terminal — монохромный консольный стиль (под клиент-роли разные цвета). Хорош для хакерских/IT-стримов.
  • glass — полупрозрачные карточки с blur-эффектом. Минимализм.
  • neon — неоновое свечение и градиенты. Под яркие сцены.
  • minimal — без рамок, только цветные ники и текст. Не отвлекает.
  • retro — пиксельный шрифт + жирные тени. Винтаж/ретро-игры.
  • bubbles — крупные пузыри с аватарой слева (имя+текст в одной строке).

URL parametersпараметры в URL

The dashboard has toggles that change URL parameters automatically. Full format:

В дашборде есть переключатели — они меняют параметры URL автоматически. Полный формат:

https://<host>/overlay/chat/<channel>?style=cards&fade=15&fadeAnim=slide-up&max=30
  • style — one of the 7 above
  • fade — after how many seconds a message disappears (0 = keep)
  • fadeAnim — fade-out animation: blur, slide-up, slide-left, scale, dissolve, glitch
  • max — how many messages to keep on screen at once
  • style — один из 7 выше
  • fade — через сколько секунд сообщение исчезает (0 = не убирать)
  • fadeAnim — анимация исчезновения: blur, slide-up, slide-left, scale, dissolve, glitch
  • max — сколько максимум сообщений держать одновременно

emotes (7TV/BTTV/FFZ)эмодзи (7TV/BTTV/FFZ)

Third-party emotes are loaded automatically — both global packs and your channel-specific emotes. To add memes (KEKW, OMEGALUL, Pog, etc.) — go to 7tv.app, log in via Twitch, find the emote and click Add to Active Set. Backend picks them up in ~5 minutes.

Третьесторонние эмодзи подгружаются автоматически — и глобальные пакеты, и эмодзи конкретно твоего канала. Чтобы добавить мемные (KEKW, OMEGALUL, Pog и т.д.) — заходишь на 7tv.app, логинишься через Twitch, ищешь нужный и жмёшь Add to Active Set. Бэкенд подцепит за ~5 минут.

badgesбейджи

Real Twitch badges are used (mods get a green sword, VIP — a diamond, subs — a star, etc.). Loaded via Helix API on the first chat message.

Используются настоящие бейджи Twitch (моды получают зелёный меч, VIP — алмаз, сабы — звезду и т.д.). Подгружаются через Helix API при первом сообщении в чате.

demo modeдемо-режим

If your channel is still empty — the preview runs a demo chat with fake messages: see how the style will look in real conditions. Demo emotes are global only (KEKW and similar shared emotes won't show up until you add them yourself).

Если в дашборде канал ещё пустой — в превью идёт демо-чат с фейковыми сообщениями: посмотреть как стиль будет выглядеть в реальной обстановке. Эмодзи в демо — только глобальные (KEKW и подобные shared-эмодзи не покажутся пока ты их не добавишь себе).

known issuesизвестное

Old OBS (built-in Chromium) may "sharply" cut the top of the chat instead of smooth fade. We have a JS-fallback that renders fade manually — should work. If it doesn't — update OBS to 28+.

Старая версия OBS (Chromium встроенный) может «резко» обрезать верх чата вместо плавного fade. У нас есть JS-fallback который рендерит fade вручную — должно работать. Если не работает — обнови OBS до 28+.

/::docs::studio tools::metrics.aggregator

metrics.aggregator // chat statistics dashboard

Channel chat analytics — how many messages, who chats the most, which commands are called more often. analytics tab in the dashboard. Only the channel owner sees it.

Аналитика чата канала — сколько сообщений, кто пишет больше всех, какие команды звучат чаще. Вкладка analytics в дашборде. Видит только владелец канала.

what it showsчто показывает

  • KPI cards — messages today / unique chatters today / messages this week / month
  • messages/hour chart — line chart of chat activity for 24h / 7d / 30d (toggle)
  • top chatters — top-10 most active viewers for day / week / month with progress bars
  • KPI-карточки — сообщений сегодня / уникальных чаттеров сегодня / сообщений за неделю / месяц
  • график messages / hour — линейный график активности чата за 24 часа / 7 дней / 30 дней (переключатель)
  • top chatters — топ-10 самых активных зрителей за день / неделю / месяц с прогрессбарами

how it worksкак это работает

Bot sits in IRC chat and counts every message into an in-memory buffer (no disk writes — fast, doesn't block chat). Once every 60 seconds the buffer is flushed to a SQLite database analytics.db. The dashboard shows you aggregates — no raw messages are stored.

Бот сидит в IRC-чате и считает каждое сообщение в in-memory буфер (без записи на диск — это быстро и не блокирует чат). Раз в 60 секунд буфер сливается в SQLite-базу analytics.db. На дашборде ты видишь агрегаты — никаких raw-сообщений не хранится.

what is NOT collectedчто НЕ собирается

  • message text (only counters)
  • private/whisper messages
  • data from other channels — each streamer sees only themselves
  • тексты сообщений (только счётчики)
  • приватные/whisper-сообщения
  • данные с других каналов — каждый стример видит только себя

data collection start pointс какого момента данные

Analytics starts accumulating from the moment the bot is enabled on the channel. No historical data before that — Twitch doesn't provide it. First numbers on the chart will appear 1-2 minutes after start.

Аналитика начинает копиться с момента включения бота на канале. Исторических данных за период до подключения нет — Twitch их не отдаёт. Первые цифры на графике появятся через 1-2 минуты после старта.

roadmap

phase 2 planned: activity heatmap by hour/day-of-week, top commands (!faceit, !music), top emotes, follower growth per day, per-stream breakdown (peak viewers per each stream).

в этап 2 запланированы: heatmap активности по часам/дням недели, топ команд (!faceit, !музыка), топ эмодзи, рост followers по дням, per-stream breakdown (peak viewers за каждый стрим).

/::docs::studio tools::notifier.telegram

notifier.telegram // stream-online push в TG-канал

When stream goes live — your Telegram channel automatically gets a notification with stream preview, title and category. Message template is customizable.

Когда стрим стартует — в твой Telegram-канал автоматически прилетает уведомление с превью трансляции, заголовком и категорией. Шаблон сообщения настраивается.

how to connectкак подключить

  1. In the dashboard open the tg tab, click «Connect Telegram channel»
  2. Our bot @ClaritySyncBot opens in Telegram — hit START
  3. Bot DMs you instructions how to add it to your channel
  4. Open your channel → Manage → Administrators → Add
  5. Find @ClaritySyncBot, select, give «Post messages» right → done
  6. В дашборде открой вкладку tg, нажми «Привязать Telegram канал»
  7. Откроется наш бот @ClaritySyncBot в Telegram — жми START
  8. Бот пришлёт в личку инструкцию как добавить его в канал
  9. Открой свой канал → Управление → Администраторы → Добавить
  10. Найди @ClaritySyncBot, выбери, дай право «Публиковать сообщения» → готово

No codes to enter. Linking happens automatically — bot matches your Telegram-id (from step 2) with whoever added it to the channel (step 4), and links silently. Nothing is posted to the channel, subscribers see nothing.

Никаких кодов вводить не надо. Привязка происходит автоматически — бот сверяет твой Telegram-id (с шага 2) с тем кто добавил его в канал (шаг 4), и привязывает молча. В канал ничего не пишется, подписчики ничего не видят.

Confirmation comes to your bot DM — "Channel X linked to streamer Y".

Подтверждение приходит тебе в личку бота — «Канал X привязан к стримеру Y».

live message (live-update)живое сообщение (live-update)

A single message is sent to the channel when stream starts — and it updates every 3 minutes while stream is live. So channel subscribers see actual info: current category, viewer count, stream duration, fresh screenshot. No flood, no dozens of notifications.

В канал отправляется одно сообщение в момент старта стрима — и оно обновляется каждые 3 минуты, пока стрим в эфире. То есть зрители канала видят актуальную информацию: текущую категорию, число зрителей, длительность трансляции, свежий скриншот стрима. Никакого флуда, никаких десятков уведомлений.

When stream ends (stream.offline) — the message is auto-deleted from the channel. Feed stays clean, no "offline 3 hours ago" messages hanging.

Когда стрим заканчивается (stream.offline) — сообщение автоматически удаляется из канала. Лента остаётся чистой, не висят «3 часа назад уже не онлайн» сообщения.

Telegram limit: bot can delete messages only within 48 hours after posting. Streams rarely last longer — but if yours exceeds 48h, the message stays.

Лимит Telegram: удалять сообщения через бота можно только в течение 48 часов после публикации. Стримы редко длятся дольше — но если вдруг твой стрим больше 48ч, сообщение останется висеть.

message templateшаблон сообщения

Template is edited in the tab. Available variables (all updated in real time):

Шаблон редактируется на вкладке. Доступные переменные (все обновляются в реальном времени):

  • {streamer} — your Twitch display-name
  • {title} — current stream title
  • {game} — current category / game
  • {viewers} — current viewer count
  • {duration} — how long you've been live (e.g. 2h 17m)
  • {link} — link to your channel
  • {streamer} — твой display-name на Twitch
  • {title} — текущий заголовок трансляции
  • {game} — текущая категория / игра
  • {viewers} — текущее число зрителей
  • {duration} — сколько ты уже в эфире (например 2ч 17м)
  • {link} — ссылка на твой канал

Telegram HTML formatting supported: <b>, <i>, <a href="...">, <code>.

Поддерживается HTML-форматирование Telegram: <b>, <i>, <a href="...">, <code>.

Default template:Дефолтный шаблон:

🔴 <b>{streamer}</b> · LIVE

<b>{title}</b>

🎮 {game}
👥 {viewers} зрителей
⏱ в эфире {duration}

🔗 <a href="{link}">{link}</a>

inline buttoninline-кнопка

Each message automatically gets a ▶️ watch stream button — click goes straight to your Twitch channel. Viewers don't need to copy the link from text.

Под каждым сообщением автоматически появляется кнопка ▶️ смотреть стрим — клик ведёт прямо на твой Twitch-канал. Зрителю не нужно копировать ссылку из текста.

stream previewпревью стрима

A fresh stream screenshot is attached to the message (Twitch updates it every ~5 min). On each live-update we force Telegram to re-fetch the image so preview stays current. If screenshot doesn't load — message comes as text without image (fallback).

К сообщению прикрепляется свежий скриншот трансляции (Twitch обновляет его каждые ~5 минут). При каждом live-update мы заставляем Telegram пере-скачать картинку, чтобы превью всегда было актуальным. Если скриншот не подгружается — сообщение придёт текстом без картинки (fallback).

test buttonтест-кнопка

There's a send test button — sends a fake notification with your nick and Just Chatting category. Handy to check bot can actually post (if rights are missing — you'll see it immediately).

На вкладке есть кнопка отправить тест — она шлёт фейковое уведомление с твоим ником и категорией Just Chatting. Удобно проверить что бот реально может писать в канал (если прав не хватает — тут это сразу видно).

anti-floodантифлуд

If stream dies and comes back in 10 minutes (internet blink) — no repeat notification. Protects against "jumping" alerts in your TG channel.

Если стрим упал и поднялся за 10 минут (интернет моргнул) — повторное уведомление не отправится. Это защита от «прыгающих» алертов в TG-канале.

unlinkingотвязка

The unlink channel button on the tab — or just remove the bot from channel admins. Either way the link is removed, channel gets no more messages.

Кнопка отвязать канал на вкладке — или просто удали бота из админов канала. В обоих случаях привязка снимается, в канал больше ничего не приходит.

limitationsограничения

  • One Twitch account = one TG channel. Multiple channels simultaneously not yet supported.
  • Kick streamers can't link TG yet (different identification model, will add later).
  • Messages are visible only to those subscribed to the channel — it's a channel post, not a DM.
  • Один Twitch-аккаунт = один TG-канал. Несколько каналов одновременно пока не поддерживается.
  • Kick-стримеры пока не могут привязать TG (другая модель идентификации, добавим позже).
  • Сообщения может видеть только тот, кто подписан на канал — это публикация в канал, не личное сообщение.
/::docs::platforms::twitch

twitch integration

bot accountаккаунт бота

shizick666 — single bot account for all Twitch channels.

shizick666 — единый аккаунт бота для всех Twitch-каналов.

how to authorizeкак авторизоваться

On /login type 1 or twitch. Twitch OAuth opens — grant access.

На странице /login введи 1 или twitch. Откроется OAuth страница Twitch — разреши доступ.

messagesсообщения

Bot sends via official Helix /chat/messages endpoint — this gives your stream a bot badge in chat (same as other "Verified Bot" accounts).

Бот отправляет через официальный Helix /chat/messages endpoint — это даёт твоему стриму бот-значок в чате (как у других "Verified Bot" аккаунтов).

not supportedчто не поддерживается

  • Message pin — Twitch doesn't expose API for third-party (only via web cookies)
  • Subscriber events — partially via EventSub, not everywhere
  • Pin сообщений — Twitch не предоставляет API для third-party (только через web-cookies)
  • Subscriber events — частично через EventSub, не везде
/::docs::platforms::kick

kick integration

bot accountаккаунт бота

sh1zick — single bot account for all Kick channels.

sh1zick — единый аккаунт бота для всех Kick-каналов.

how to addкак добавить

  1. On /login type 2 or kick
  2. Authorize via Kick OAuth
  3. In the dashboard switch to your Kick channel (target dropdown)
  4. In Kick chat give bot mod rights: /mod sh1zick
  5. На /login введи 2 или kick
  6. Авторизуй через Kick OAuth
  7. В дашборде переключись на свой Kick-канал (target dropdown)
  8. В чате Kick выдай боту мод-права: /mod sh1zick

what worksчто работает

  • Faceit (!elo, !lobby, etc.)
  • Custom commands + templating
  • Economy
  • Trivia + autostart
  • Mini-games / lottery
  • Giveaways + timers
  • Moderation (link/banword filter)
  • Stream control (!title, !game, quick-cats)
  • Music (!track)
  • Faceit (!elo, !lobby и т.д.)
  • Кастомные команды + шаблонизатор
  • Экономика
  • Trivia + автозапуск
  • Mini-games / lottery
  • Giveaways + timers
  • Moderation (фильтр ссылок/банвордов)
  • Стрим-управление (!title, !game, quick-cats)
  • Music (!трек)

notesособенности

On Kick new accounts may not be allowed to post links — it's blocked by Kick itself, not our bot. Fixed by account verification or mod rights on the channel where it posts.

На Kick новые аккаунты могут не иметь права писать ссылки — это блокирует сам Kick, не наш бот. Решается верификацией аккаунта или mod-правами на канале где он пишет.

/::docs::public api::nightbot

public faceit api // for nightbot / streamelements / fossabot

Any streamer can add Faceit commands to their Nightbot (or StreamElements / Fossabot) via our public API — no registration, no auth.

Любой стример может добавить Faceit-команды в свой Nightbot (или StreamElements / Fossabot) через наш публичный API — без регистрации, без авторизации.

API returns plain text, cached for 60 seconds, limited to 400 chars (Nightbot's limit for $(urlfetch)).

API возвращает plain text, кэшируется на 60 секунд, ограничен 400 символами (лимит Nightbot для $(urlfetch)).

endpoints

/api/nb/elo
current elo + today's W/Lтекущее эло + сегодняшние W/L
/api/nb/today
today's stats (W/L and ± elo)статистика за сегодня (W/L и +/- эло)
/api/nb/last
last match (map, score, K/D)последний матч (карта, счёт, K/D)
/api/nb/lobby
live status of current match (map, score, time, avg elo)live-статус текущего матча (карта, счёт, время, avg elo)

Parameter: ?nick=FaceitNick (also ?nickname=...). Case-insensitive.

Параметр: ?nick=FaceitNick (можно также ?nickname=...). Регистр не важен.

examplesпримеры

// test in browser, replace nick with yours:проверь прямо в браузере, заменив ник на свой:
https://claritysync.ru/api/nb/elo?nick=sh1zick

// response (plain text):ответ (plain text):
⭐ Lvl 10 · 2350 elo · today: 5W-2L (+45)сегодня: 5W-2L (+45)

how to add to nightbotкак добавить в nightbot

  1. Go to your Nightbot dashboard → Commands → Custom
  2. Click Add Command
  3. Fill in: 
    Name:    !elo
Message: $(urlfetch https://claritysync.ru/api/nb/elo?nick=YOUR_FACEIT_NICK)
Userlevel: Everyone
Cooldown: 5
  4. Save and test in chat with !elo
  5. Зайди в свою Nightbot dashboard → Commands → Custom
  6. Нажми Add Command
  7. Заполни: 
    Name:    !elo
Message: $(urlfetch https://claritysync.ru/api/nb/elo?nick=ТВОЙ_ФЕЙСИТ_НИК)
Userlevel: Everyone
Cooldown: 5
  8. Сохрани и проверь в чате !elo

add via chat (faster)добавить через чат (быстрее)

In your Twitch chat tell Nightbot (replace sh1zick with your faceit nick):

В своём Twitch-чате напиши Nightbot'у (вместо sh1zick — свой faceit ник):

!addcom !elo $(urlfetch https://claritysync.ru/api/nb/elo?nick=sh1zick)
!addcom !today $(urlfetch https://claritysync.ru/api/nb/today?nick=sh1zick)
!addcom !last $(urlfetch https://claritysync.ru/api/nb/last?nick=sh1zick)
!addcom !lobby $(urlfetch https://claritysync.ru/api/nb/lobby?nick=sh1zick)

streamelements / fossabot

Works identically — use the same URL inside ${urlfetch} (SE) or (customapi) (Fossabot).

Работает идентично — используй такой же URL внутри ${urlfetch} (SE) или (customapi) (Fossabot).

streamelements exampleпример streamelements

!command add !elo ${urlfetch https://claritysync.ru/api/nb/elo?nick=sh1zick}

fossabot exampleпример fossabot

!commands add !elo $(customapi https://claritysync.ru/api/nb/elo?nick=sh1zick)

limits and stabilityлимиты и стабильность

  • 60s cache — repeat requests within a minute return the same response instantly, no load on Faceit.
  • 400 char limit — long responses are auto-truncated with ….
  • Nightbot itself sets default cooldown ~5s per command — that's fine.
  • Faceit API limits our bot to ~10 req/sec, but with 60s cache it's not a problem even on big channels.
  • Кэш 60 секунд — повторные запросы за минуту отдают тот же ответ мгновенно, без нагрузки на Faceit.
  • Лимит 400 символов — длинные ответы автоматически обрезаются с ….
  • Сам Nightbot ставит cooldown по умолчанию ~5 секунд на команду — это норм.
  • Faceit API ограничивает наш бот ~10 запросов/секунду, но с кэшем 60с это не проблема даже на крупных каналах.

legacy pathsустаревшие пути

Old paths /api/public/faceit/elo etc. work the same, use whichever. The new /api/nb/* are just shorter.

Старые пути /api/public/faceit/elo и т.д. — работают так же, можешь использовать любые. Новые /api/nb/* просто короче.

/::docs::troubleshoot

troubleshoot

bot doesn't respond in chatбот не отвечает в чате

  • Check that bot is online in the dashboard
  • Check that bot is a mod on your channel (/mod shizick666 on twitch)
  • Twitch may delay messages from new bots on new channels — wait a few minutes
  • Проверь что бот online в дашборде
  • Проверь что бот — мод твоего канала (/mod shizick666 на twitch)
  • Twitch может задерживать сообщения новых ботов на новых каналах — подожди несколько минут

!track says "feature not configured"!трек пишет "функция не настроена"

Server doesn't have yt-dlp or ffmpeg installed. Admin should install:

На сервере не установлен yt-dlp или ffmpeg. Админ должен установить:

apt install -y ffmpeg
pip install yt-dlp

!track says "audd: quota exceeded"!трек пишет "audd: quota exceeded"

AudD free limit (300/mo) is used up. Need to update token in .env or wait until next month.

Закончился бесплатный лимит AudD (300/мес). Надо обновить токен в .env или подождать следующего месяца.

streamer shows offline while onlineстример показывается offline хотя онлайн

Cache refreshes every 60 seconds — wait a minute. If still offline — ping us, we'll check logs.

Cache обновляется раз в 60 секунд — подожди минуту. Если всё равно offline — пиши, посмотрим логи.

/::docs::contact

contact / about

$ cat ~/about.txt

coder. ~2 years deep in python — asyncio, quart, twitchio,
some frontend (vanilla js, html, css), deploys on linux-vps,
nginx, systemd. love when everything works by itself and quietly.

clarity is my main long-term project.
started as a simple twitch-bot for my own channel, grew into
a multi-platform thing with kick integration, faceit live-summaries,
economy, mini-games, shazam-style music recognition and
a full web dashboard.

i do everything myself: backend, frontend, deploy, support, docs.
open to commercial projects, bot/integration gigs and just
interesting collabs.
кодер. ~2 года плотно в python — asyncio, quart, twitchio,
немного frontend (vanilla js, html, css), деплой на linux-vps,
nginx, systemd. люблю когда всё работает само и тихо.

clarity — мой основной долгосрочный проект.
начинал как простой twitch-бот для своего канала, вырос до
multi-platform штуки с kick-интеграцией, faceit live-сводками,
экономикой, мини-играми, шазам-распознаванием музыки и
полноценным веб-дашбордом.

делаю всё сам: backend, frontend, deploy, support, документация.
открыт к коммерческим проектам, заказам на ботов / интеграции
и просто интересным коллабам.

$ whoami --details

role     :: developer / admin / solo
nickname :: sh1zick
since    :: ~2 years in python
stack    :: python · asyncio · quart · twitchio · kick api · sqlite · aiohttp
frontend :: vanilla js · html · css (without frameworks, on purpose)
deploy   :: ubuntu vps · systemd · nginx
status   :: open for work

twitch   :: twitch.tv/shizick666
kick     :: kick.com/sh1zick
telegram :: t.me/sh1zick666
email    :: shizick@claritywork.ru
← back to dashboard