Welcome! This page covers everything you need to run overlays on your stream — from your first login through every widget available. If you're brand new, start with Getting Started right below and work down; if you're back for something specific, jump straight to it from the list.
1. Getting Started
Go to /auth/login and click Continue with Twitch. That's it — your
display name, a random overlay-URL identity, and a Q&A link are all created automatically on
first login. There's nothing to fill in.
If you were given a username and password instead of Twitch login (rare — this is normally only used for the platform's super admin account), you'll fill in a display name once and you're in.
2. Your First Overlay
- From your dashboard, type a name under New Overlay and click Create Overlay.
- Click Edit on the new overlay card to open the canvas editor.
- Pick a widget from the dropdown and click Add Widget. Drag it into position, drag the small handle in its bottom-right corner to resize it, and click it to open its settings panel on the right.
- Copy the OBS Browser Source URL from the top of the editor.
- In OBS: Sources → + → Browser, paste the URL, and set the width/height to match your overlay's canvas size (1920×1080 by default).
Changes you make in the editor apply instantly — no need to refresh the Browser Source in OBS while designing, though a refresh never hurts if something looks stale.
3. Widget Catalog
| Widget | Tier | Fed by | What it does |
|---|---|---|---|
| Countdown Timer | Free | Set-and-forget, or push a new time via the API | A clock counting down to a duration you set. |
| Goal Bar | Free | Twitch alerts (auto) or manual push | Progress bar toward a sub/follow/donation goal. |
| Live Poll | Free | Twitch chat (!1–!4) | Up to 4 options with live vote bars. |
| Leaderboard | Free | Twitch chat (auto) or manual push | Top chatters by message count this session. |
| Now Playing | Free | Manual push only | Current track display — no built-in music source. |
| Image | Free | You set it in config | Displays an image from your Media Library. |
| Live Q&A | Free | Q&A moderation panel | Shows whichever question you've marked "live." |
| Alert Box | Premium | Twitch alerts (auto) or manual push | Pop-up card for follows/subs/cheers/raids, with optional sound. |
| Chat Overlay | Premium | Twitch chat (auto) | Scrolling ticker of recent chat messages. |
| Emote Wall | Premium | Twitch chat (auto) | Emotes people actually use in chat float across the screen. |
| Custom HTML/CSS/JS | Premium | Whatever you build | A sandboxed iframe for anything not covered above. |
"Auto" means it works the moment you've linked Twitch — nothing else to configure. "Manual push" means something (a bot, a script, or you) needs to call the API described in section 10.
4. Twitch Integration (Alerts & Chat)
Linking Twitch turns on two independent systems:
Follow/Sub/Cheer/Raid Alerts (EventSub)
Twitch's webhook system tells OverlayHub the moment someone follows, subscribes, cheers, or raids. This feeds the Alert Box and Goal Bar widgets. Configure which events trigger them in each widget's own config panel:
- Alert Box:
autoEventTypes— comma-separated, e.g.follow,subscribe,raid - Goal Bar:
autoIncrementOn— comma-separated, e.g.subscribe,cheer. Cheers increment by bit amount; everything else by 1.
Live Chat
OverlayHub also reads your chat directly (read-only, no bot account) to power Live Poll, Leaderboard, Chat Overlay, and Emote Wall. This is always on once Twitch is linked — nothing to turn on separately.
Poll voting: viewers type !1, !2, !3, or !4 in
chat, matching whichever option numbers you've filled in on the poll's config panel. Each viewer's
vote counts once per poll — use Reset Poll Votes in the config panel to start over.
5. Media Library
Go to Media Library from your dashboard to upload images (PNG/JPEG/GIF/WEBP/SVG) and sounds (MP3/WAV/OGG), up to 25MB per file. Click Copy URL on anything you've uploaded, then paste that URL into:
- The Image widget's Image URL field
- Alert Box's Sound URL field, to play a sound on alert
Your total storage is capped by your plan (see section 7) — the library page shows how much you've used.
6. Live Q&A
Every account gets a public question page at /ask/<your-link> — find your exact
link at the top of Q&A Moderation. Share it in your Discord, panels, or chat.
Viewers submit anonymously or with a name, no login required.
From the moderation panel: Approve a question, then Go Live to push it to any Live Q&A widgets on your overlays instantly. Clear from Overlay hides it again. Only one question is live at a time.
7. Free vs Premium
| Free | Premium | |
|---|---|---|
| Overlays | 2 | 25 |
| Widgets per overlay | 6 | 40 |
| Storage | 50MB | 1000MB |
| Watermark on overlay | Yes | No |
| Alert Box, Chat Overlay, Emote Wall, Custom HTML | — | Included |
Contact the platform admin to upgrade your account.
8. Account & Security
Everything below lives on your Settings page:
- Link Twitch Account — if you started with a local username/password, connect Twitch afterward to unlock alerts and chat features, without losing your existing overlays.
- Regenerate API Key — if a bot or script with your key is compromised or decommissioned, this immediately invalidates the old one.
- Regenerate Q&A Link — invalidates your old public question link immediately.
- Regenerate URL (per overlay, on that overlay's edit page) — if an OBS Browser Source URL ever leaks, this kills the old one instantly. You'll need to paste the new URL into OBS.
9. Building Your Own Widget (Custom HTML)
The Custom HTML/CSS/JS widget (Premium) is the escape hatch for anything not covered by a built-in widget. It renders your HTML/CSS/JS inside a sandboxed iframe on your overlay. To receive live updates (e.g. from a manual API push), your JS can call:
onUpdate(function(payload) {
// payload is whatever JSON was pushed via /api/events
document.body.textContent = JSON.stringify(payload);
});
10. Pushing Your Own Data (API for bots)
Any widget instance can be updated directly with a simple API call — useful for your own bots,
scripts, or automations. Find your api_key on the Settings page, and each widget
instance's ID by hovering it in the canvas editor (visible in the block's data as you configure it).
POST /api/events
Content-Type: application/json
{
"api_key": "your_api_key",
"widget_instance_id": 42,
"payload": { "title": "New Follower!", "body": "SomeViewer just followed" }
}
The shape of payload depends on the widget type — matching what that widget's own
automatic feed sends is always a safe bet (e.g. Goal Bar takes {"delta": 1} or
{"current": 50}; Alert Box takes {"title": "...", "body": "..."}).
This endpoint is rate-limited to 120 calls/minute per API key.
11. Troubleshooting
My alerts stopped firing
Check your dashboard for a banner naming which alert types disconnected — this happens if you revoke OverlayHub's access on Twitch's side. Click Reconnect Twitch Alerts to restore it.
Chat-powered widgets (Poll, Leaderboard, Chat Overlay, Emote Wall) aren't updating
These read your live chat directly and reconnect automatically — if they've been idle a long time, try leaving and re-entering your own stream chat, or contact the platform admin if it persists.
My overlay isn't showing in OBS
Confirm you copied the full URL from the editor's toolbar, and that you haven't since clicked Regenerate URL (which invalidates the one OBS still has cached).
A widget says it needs Premium
See section 7 — contact the platform admin to upgrade.