CuervoBot
Complete user manual for every feature of your Twitch streaming dashboard
What is CuervoBot?
Your all-in-one streaming assistant for Twitch — manage rewards, chat, alerts, and overlays from one place.
CuervoBot is a desktop application that runs on your computer while you stream. It connects to your Twitch channel and gives you a live dashboard where you can see chat messages, channel-point reward redemptions, manage your rewards, and much more — all without leaving your streaming setup.
🏆 Rewards Feed
See every channel-point reward redeemed by viewers in real time, with the user name, reward title, and cost.
🔔 Channel Alerts
Configure browser-source alerts for follows, subscriptions, bits, raids, and more that appear on screen in OBS.
⚙️ Manage Rewards
Create, edit, and delete Twitch channel-point rewards directly from the dashboard without visiting Twitch settings.
🎮 Game Detector
Automatically detects the game you're playing via Steam or Discord and updates your Twitch category for you.
🎵 Spotify Integration
Show the currently playing song on screen and let viewers request songs through channel-point rewards.
🤖 Chatbot
Respond to chat commands like !roll and !8ball, send timed messages, and filter spam automatically.
🔊 Text-to-Speech
Have chat messages and reward redemptions read aloud through your speakers using your browser's built-in voice engine.
🖥️ OBS Overlays
Add browser-source overlays to OBS for reward animations, now-playing widgets, and category-change announcements.
Quick Start Checklist
Follow these steps the first time you open CuervoBot to get everything up and running.
-
✓Install the application
Download and run the CuervoBot_Setup.exe installer (Windows) or the .app bundle (macOS). Follow the on-screen prompts — no administrator password is needed on Windows. -
Open CuervoBot
Launch the application from your Desktop shortcut or Start Menu. A local dashboard will open in a window automatically. -
Connect with Twitch
Click the purple "Connect with Twitch" button in the top-right corner. Your browser will open the official Twitch authorization page. Log in and click Authorize. -
Confirm connection
Once authorized, the dashboard shows your Twitch profile picture and username in the top-right. The status indicator turns green with the word Connected. -
Explore the tabs
Click through the sidebar tabs on the left — Rewards, Alerts, Manage, Game Detector, Chatbot, TTS — and configure each one to your liking. -
Add overlays to OBS (optional)
If you use OBS, add Browser Sources pointing to the overlay URLs shown inside the dashboard. See the OBS Overlays section for step-by-step instructions.
Twitch Login
CuervoBot uses the official Twitch login — your password is never stored by the app.
Click "Connect with Twitch"
Look for the purple button in the top-right corner of the dashboard. If you see your profile picture instead, you are already logged in — skip to step 4.
Authorize on Twitch's website
Your default web browser opens the official twitch.tv authorization page. Enter your Twitch username and password (if not already logged in), then click Authorize. This grants CuervoBot permission to read your channel data and manage rewards.
Return to the dashboard
The browser tab closes automatically and the dashboard updates. You will see a toast notification confirming the connection.
You're connected!
Your profile picture, display name, and @username appear in the top-right. The green status dot means the dashboard is receiving live events from Twitch.
Logging out
Click your profile picture in the top-right and then the Log Out button. All real-time connections are closed. You can log back in at any time.
Rewards Feed
A live feed of every channel-point reward redeemed by your viewers during the current stream session.
Every time a viewer redeems a channel-point reward, a new card instantly appears at the top of this feed. You do not need to do anything — it updates automatically.
📊 Session Statistics
The ribbon at the top shows total rewards claimed, chat messages, active rewards configured, and total points spent — all updated in real time.
✨ High-Value Highlight
Redemptions costing 1,000 points or more get a special visual effect so you never miss an expensive reward being claimed.
🗑️ Clear Feed
Click the Clear button at the top-right of the tab to empty the feed and reset the session counter. This does not affect your actual Twitch rewards.
Channel Alerts
Configure and preview on-screen alerts for follows, subscriptions, bits, raids, and more.
Alerts are short animations or sounds that play on your stream when a viewer does something special — like subscribing or raiding. CuervoBot lets you attach a custom video, image, GIF, or audio clip to each alert type.
| Alert Type | Icon | When it fires |
|---|---|---|
| Follow | 👤 | A new viewer follows your channel |
| Subscribe | ⭐ | A viewer subscribes for the first time |
| Re-subscribe | 🔄 | A subscriber renews their subscription |
| Gift Sub | 🎁 | A viewer gifts a subscription to someone |
| Cheer (Bits) | 💎 | A viewer cheers with bits |
| Raid | ⚔️ | Another streamer raids your channel |
| Gigantify Emote | 🔮 | A viewer uses the Gigantify Emote channel reward |
How to configure an alert
Click the alert card you want to configure
Each alert type has its own card in the grid. Click the Edit or pencil icon on the card to open its editor.
Paste a media URL
In the editor, paste the URL of a video, GIF, image, or audio file you want to play. This can be a link to a file hosted online (e.g. a Dropbox or Google Drive direct link).
Set the duration
Choose how many seconds the alert stays on screen. A good starting point is 5–8 seconds.
Position on screen
Use the position editor to drag the alert to the exact spot you want it to appear on your stream. You can also set width, height, and opacity.
Save and add the OBS overlay
Click Save, then click Open Overlay at the top of the Alerts tab. Copy the URL that appears and add it as a Browser Source in OBS.
Manage Rewards
Create, edit, enable/disable, and delete your Twitch channel-point rewards without opening Twitch settings.
Creating a new reward
Click "➕ New Reward"
A form slides in on the right side of the screen.
Fill in the required fields
Title (max 45 characters) — what viewers see on the reward button.
Cost in Points — how many channel points to redeem it. Use a higher cost for rarer rewards.
Optional: add extra settings
Description — explains the reward to viewers.
Require user input — viewers must type a message when redeeming (e.g. for song requests).
Background color — the reward button's color on Twitch.
Global cooldown — minimum seconds between any redemption.
Max per stream / per user — limits how many times it can be redeemed.
Click "Create Reward"
CuervoBot sends the new reward to Twitch. It appears on your channel immediately.
Game Detector
Automatically detects the game you are playing and updates your Twitch stream category — no manual updates needed.
CuervoBot watches which game is running on your computer via Steam or Discord Rich Presence, compares it to your current Twitch category, and changes the category automatically after a short grace period.
🟢 Auto-detect from Steam
If you launch a Steam game, the detector picks it up and maps it to the correct Twitch category name.
🟦 Discord Rich Presence
Any game that reports its name to Discord can also trigger the detector — useful for non-Steam games.
⏱️ Grace Period
After detecting a game switch, CuervoBot waits a configurable number of seconds before updating Twitch. You can cancel the update before it fires.
💬 Idle Category
When no game is detected for a set idle time, the category automatically switches to Just Chatting (or whatever you configure).
Settings explained
| Setting | What it does | Default |
|---|---|---|
| Grace Period (seconds) | How long to wait before actually changing the Twitch category. Gives you time to cancel. | 15 s |
| Idle Timeout (seconds) | If no game is detected for this many seconds, switch to the Idle Category. | 100 s |
| Idle Category | The Twitch category used when no game is running. | Just Chatting |
| Discord User ID | Your Discord User ID, used to read your Rich Presence game status. | Your account |
When a game is detected, a small toast appears in the bottom corner of the dashboard showing: "Detected: [Game Name] — Updating category in 15s…" with a Cancel button. Click Cancel if you do not want the category to change.
Category Change Widget (OBS)
You can display a beautiful on-screen widget whenever your category changes. Click "Configure Overlay" at the top of the Game Detector tab to open the widget editor. Choose a skin, colors, and position, then copy the URL and add it as a Browser Source in OBS.
Spotify Integration
Show the currently playing song on stream and let viewers request songs with channel points.
Connecting Spotify
Open the Spotify tab
Click Spotify in the left sidebar under Detection & Media.
Click "Connect Spotify"
A browser window opens with the official Spotify login page. Log in and authorize CuervoBot to read your playback and control your queue.
Return to the dashboard
Once authorized, the Spotify tab shows a green "Connected" pill and the currently playing track updates every 7 seconds.
Operating modes
🔇 Disabled
Spotify is connected but CuervoBot does not interact with it. The now-playing widget still works.
💬 Chat Command
Viewers type a command (e.g. !sr Despacito) in chat to add a song to the queue.
🏆 Channel Point Reward
Viewers redeem a channel-point reward and type the song name in the reward input box. CuervoBot adds it to the queue automatically.
Chatbot
Automate chat responses with custom commands, timed messages, spam filtering, and an AI assistant.
The master toggle at the top of the Chatbot tab enables or disables all chatbot features at once. When off, no automated messages are sent.
📝 Custom Commands
Commands let viewers type a short message starting with ! to get an automated response. For example, typing !discord could make the bot post your Discord invite link.
Click "Add Command"
A dialog box appears with fields to fill in.
Fill in Command Name and Response
Name: the word after ! (e.g. roll → viewers type !roll).
Response: what the bot posts in chat. You can use special placeholders (see table below).
Set the Cooldown and Permission Level
Cooldown prevents the command from being spammed — minimum seconds between uses.
User level: Everyone, Subscriber, Moderator, or Broadcaster only.
Click Save
The command is now live. Test it by typing it in your Twitch chat.
✨ Response Placeholders
| Placeholder | Replaced with |
|---|---|
{{user}} | The display name of the viewer who used the command |
{{target}} | The username mentioned after the command (e.g. !hug @friend) |
{{args}} | Everything the viewer typed after the command name |
{{random:1-6}} | A random number between 1 and 6 (dice roll) |
{{choose:A|B|C}} | A random choice from the list (A, B, or C) |
{{love_score}} | A random "love score" percentage |
Click the Preset dropdown in the command dialog to quickly fill in ready-made commands like
!roll (dice), !8ball (magic 8-ball), and !hug.
⏰ Timed Messages
Timed messages are automatic posts sent at regular intervals — useful for reminding viewers about your social links, donation goals, or rules.
| Setting | What it means |
|---|---|
| Message | The text the bot will post in chat |
| Interval (minutes) | How often the message is sent (e.g. every 30 minutes) |
| Min chat lines | The minimum number of chat messages that must have been sent since the last post — prevents the bot from posting to an empty chat |
🛡️ Spam Filter
The spam filter automatically times-out or deletes messages that match certain patterns. All settings are saved when you click Save Settings.
🔠 Caps Filter
Detects messages with too many CAPITAL LETTERS. Set the threshold percentage — e.g. 70 % means a message is flagged if more than 70 % of letters are uppercase.
🔗 Link Filter
Removes or times out viewers who post URLs in chat. You can add a list of allowed domains (e.g. your own website) that are exempt from the filter.
📋 Word Blacklist
Enter words or phrases (one per line) that will automatically trigger an action when detected in chat.
⚡ Action
Choose what happens when spam is detected: Timeout (temporary ban) for a set number of seconds, or Delete (just remove the message).
🧠 Ollama AI Assistant (Local AI)
Connect a locally running Ollama AI model to respond to chat questions. Viewers type the trigger command (default !ask) followed by a question.
qwen2.5:7b). This is an advanced feature — if you are unsure, skip this section.| Setting | Description |
|---|---|
| Enabled | Toggle the AI assistant on or off |
| Host | The address of your Ollama server (default: http://localhost:11434/) |
| Model | The model name to use (e.g. llama3.2:3b) |
| Command | The chat command that triggers the AI (default: ask) |
| Cooldown | Seconds between AI responses to prevent spam |
| System Prompt | Instructions that shape the AI's personality and rules |
Text-to-Speech (TTS)
Have chat messages and reward redemptions read aloud through your speakers.
TTS uses your computer's built-in speech engine (free) to convert text to audio. Enable it to hear your chat without looking at the screen, or to entertain your audience with automated readouts.
TTS Settings
| Setting | What it does |
|---|---|
| Enabled | Master on/off switch for all TTS |
| Voice | Choose from any voice installed on your computer |
| Speed (Rate) | How fast the voice speaks. 1.0 is normal speed |
| Pitch | How high or low the voice sounds. 1.0 is normal |
| Volume | How loud the voice is. 1.0 is maximum |
| Max Length | Messages longer than this many characters are cut off (prevents very long reads) |
| Read username | When on, the bot says "Username says: message" instead of just the message |
| Event-only mode | When on, chat messages are NOT read — only rewards, alerts, and bits |
Trigger Sources
Choose which events trigger TTS. Enable only the ones you want:
💬 Chat
Every chat message is read aloud. Commands starting with ! are automatically skipped.
🔔 Alerts
Follows, subscriptions, and similar events trigger a TTS announcement.
🏆 Rewards
When a viewer redeems a channel-point reward, the redemption is read aloud.
💎 Bits
Bit cheers are read aloud. Set a minimum bits amount to skip small cheers.
Reward Queue PRO
Review pending channel-point redemptions and approve or deny them one by one.
When a reward requires manual fulfillment (the Skip Queue option is off on the reward), it lands in the Reward Queue. This tab lets you review each redemption, see what the viewer typed, and decide whether to fulfill or cancel it.
✅ Approve
Marks the redemption as fulfilled. The viewer's points are consumed and the reward is completed.
❌ Deny / Refund
Cancels the redemption and refunds the points to the viewer automatically.
🔄 Real-time updates
New redemptions appear instantly via WebSocket — no need to refresh the page.
AI TTS — ElevenLabs PRO
Upgrade from the browser's robotic voice to a human-sounding AI voice powered by ElevenLabs.
ElevenLabs provides ultra-realistic AI voices. With a Pro subscription and your own ElevenLabs API key, CuervoBot can read chat and rewards using these voices instead of the default browser voice.
Get an ElevenLabs API key
Create a free or paid account at elevenlabs.io, then go to your profile settings to copy your API key.
Paste the key in the TTS tab
Open the TTS tab and scroll to the AI TTS (ElevenLabs) section. Paste your API key in the field provided.
Choose a voice
Click Load Voices to fetch the voices available in your ElevenLabs account, then select one from the dropdown.
Adjust stability and similarity
Stability controls how consistent the voice sounds (higher = more stable). Similarity controls how closely the output matches the original voice sample.
Subscription & Pro Plan
Unlock advanced features with a Pro license key.
| Feature | Free | Pro |
|---|---|---|
| Rewards Feed | ✅ | ✅ |
| Channel Alerts | ✅ | ✅ |
| Manage Rewards | ✅ | ✅ |
| Game Detector | ✅ | ✅ |
| Spotify Integration | ✅ | ✅ |
| Chatbot (commands, spam filter) | ✅ | ✅ |
| Basic TTS (Web Speech) | ✅ | ✅ |
| Reward Queue | 🔒 | ✅ |
| AI TTS (ElevenLabs) | 🔒 | ✅ |
| Claude AI Chatbot | 🔒 | ✅ |
| Pro Media Library | 🔒 | ✅ |
Activating your license
Purchase a license
Click the Buy Now button in the Pro tab of the dashboard. Complete the purchase on the payment page.
Copy your license key
After purchase, you receive a license key by email. It looks like a long sequence of letters and numbers.
Paste and activate
In the Pro tab, paste the key into the License Key field and click Activate. A success message confirms activation and all Pro features unlock immediately.
OBS Overlays
Add CuervoBot's visual overlays to OBS as Browser Sources to show alerts, animations, and widgets on stream.
CuervoBot runs a local web server on your computer. Each overlay is a web page at a special URL like http://localhost:8080/overlay?reward_id=…. You add these URLs to OBS as Browser Sources.
Adding a Browser Source in OBS
Copy the overlay URL from CuervoBot
In the relevant tab (Alerts, Game Detector, Spotify, etc.) click the "Open Overlay" or "Configure Overlay" button. A dialog shows the URL — copy it.
Add a Browser Source in OBS
In OBS, click the + button in the Sources panel → choose Browser → give it a name (e.g. "Alert Overlay") → click OK.
Paste the URL
In the Browser Source properties, paste the copied URL in the URL field. Set the width and height to match your stream resolution (usually 1920 × 1080). Click OK.
Test the overlay
Right-click the Browser Source in OBS → click Interact to open a preview. Trigger a test event from CuervoBot to see it fire on screen.
Available overlay pages
| Overlay | URL / where to find it | What it shows |
|---|---|---|
| All-in-One Overlay ⭐ | Alerts → Open Overlay button/overlay/all |
Plays all rewards + all alerts in one queued browser source — the recommended single source to add to OBS |
| Per-Reward Overlay | Alerts → individual reward card editor | Plays media only for one specific reward ID |
| Now Playing | Spotify → Now Playing tab | Current Spotify track, artist, album art |
| Category Change Widget | Game Detector → Configure Overlay | On-screen announcement when Twitch category changes |
All-in-One Overlay Recommended
A single OBS Browser Source that plays every reward animation and every channel alert — automatically queued so nothing overlaps.
Instead of adding a separate Browser Source for each reward or alert, the All-in-One Overlay handles everything in one place. When multiple events fire at the same time, it queues them and plays each one in order, so your viewers never miss an animation.
Clicking Open Overlay in the Alerts tab or in any reward editor opens this same overlay at
http://localhost:PORT/overlay/all. Copy that URL and add it as a Browser Source in OBS — you only need one Browser Source for all your rewards and alerts combined.
🏆 All Reward Animations
When any channel-point reward is redeemed, this overlay looks up that reward's configured media (video, GIF, image, audio) and plays it automatically.
🔔 All Channel Alerts
Follows, subscriptions, re-subs, gift subs, bits, raids, and gigantify-emote events all play through the same overlay using their individually configured media.
📋 Built-in Queue
If a raid happens while a reward animation is playing, the raid alert waits its turn. Events are queued up to 50 deep and played one after another with no overlap.
🔄 Live Config Refresh
Media configurations are re-fetched before each animation plays, so any changes you make in the editor take effect immediately — no need to reload the OBS source.
How to set it up
Configure your reward and alert media
In the Alerts tab, set a media URL and duration for each alert type (follow, sub, bits, etc.). In the reward editor, assign media to each reward. The all-in-one overlay plays whatever you configured per-event.
Click "🖥️ Open Overlay" in the Alerts tab
A new browser tab opens showing the overlay page. Copy the URL from the address bar — it will look like http://localhost:PORT/overlay/all.
Add it as a Browser Source in OBS
In OBS: Sources → + → Browser. Paste the URL, set width/height to your stream resolution (1920×1080), and check "Shutdown source when not visible" so it doesn't play while off-screen.
Test it
Trigger a test by redeeming a channel-point reward or having someone follow your channel. The animation should appear directly in OBS within a second.
Now Playing Widget
A live OBS Browser Source that shows the current Spotify track, artist, and album art.
This widget updates automatically every few seconds. It displays the song title, artist name, and album art in a beautiful animated card that you can position anywhere on your stream.
Skins
Open the Now Playing tab and click the Edit (pencil) button to open the skin editor. Choose from several visual styles:
🌫️ Blur
Frosted-glass card with blurred album art background. Clean and modern.
🎵 Classic
Simple card with album art thumbnail on the left and track info on the right.
⚡ Minimal
Just the song title and artist in small text — perfect for a subtle corner display.
🌈 Neon
Glowing neon-colored text for a retro arcade feel.
Category Change Widget
An animated on-screen announcement that appears whenever your Twitch category changes.
When the Game Detector (or a manual category change) updates your Twitch category, this widget briefly appears on your stream showing the new game/category name. It fades in, holds for a few seconds, then fades out automatically.
Widget Skins
| Skin | Look |
|---|---|
| Classic | Simple card with game name and icon |
| Minimal | Just text, no background frame |
| Retro | Pixelated retro-gaming style frame |
| Neon | Glowing neon border and text |
| Banner | Full-width banner across the top or bottom |
| Badge | Small pill/badge — ideal for a corner display |
Customizing the widget
Open the editor
In the Game Detector tab, click "🎨 Configure overlay". The editor opens.
Choose a skin and colors
Pick a skin from the dropdown. Then set the background color, accent color, title color, and text color using the color pickers.
Set position, scale, and duration
X / Y: position on screen in pixels. Scale: resize the widget (1.0 = normal size). Duration: how many milliseconds it stays visible (6000 = 6 seconds).
Save and add to OBS
Click Save, then copy the overlay URL from the editor and add it as a Browser Source in OBS (see OBS Overlays).
logs/ folder in the application directory for troubleshooting details.