Twitch Notifications
Instant go-live alerts for your Discord server
The Twitch Notifications module lets your bot watch up to 25 Twitch streamers and automatically post a message in a Discord channel the moment they go live. Notifications arrive within seconds using Twitch's EventSub push model — no polling, no API quota burn.
Overview
Once a streamer is added and a target Discord channel is selected, the bot subscribes to Twitch's EventSub webhook for that streamer. When Twitch detects a stream going live, it pushes a signed event to TeraOne's server within seconds. The bot then posts the configured message template — including stream title, game, and a direct Twitch link — to the chosen Discord channel.
Setup
- Open the Twitch Notifications tab in the dashboard and enable the module
- Enter a Twitch username or channel URL and click Add
- Select the target Discord channel where go-live alerts should be posted
- Optional: customize the message template and add role mentions
- Save — the bot immediately registers the EventSub subscription with Twitch
Features
The Twitch Notifications dashboard tab provides the following controls per streamer subscription:
| Feature | Description |
|---|---|
| Add streamer | Search by Twitch login name or channel URL. The bot validates the account and shows a preview (display name, profile image, follower count). |
| Edit subscription | Change the target Discord channel, update the message template, add or remove role mentions, or temporarily disable the subscription without deleting it. |
| History tab | Per-subscription log of all recent notifications: stream title, game, target channel, status (sent / failed / skipped), timestamp, and error detail on failure. |
| Message template | Freeform text with placeholder variables. The template supports Discord Markdown and mentions. Up to 2,000 characters. |
| Role mentions | Attach up to 20 Discord roles to be pinged in the notification post. The mentions are prepended automatically before the template text. |
| Test preview | Send a simulated go-live message to the target channel with realistic dummy data to verify layout and permissions before a real stream starts. |
Template variables
Use these placeholders in your message template. They are replaced with live stream data at the moment the notification is sent:
| Variable | Content |
|---|---|
{streamer} | Display name of the Twitch channel (e.g. Pokimane) |
{login} | Lowercase login name (e.g. pokimane) — useful for building the Twitch URL manually |
{title} | Stream title at the moment the go-live event fired |
{game} | Category / game name the streamer selected (e.g. Valorant) |
{url} | docs.twitch-notifications.template_variables.row_url_desc |
{started_at} | ISO 8601 timestamp of when the stream started (UTC) |
How it works
Twitch Notifications use the EventSub push model instead of polling:
- When you add a streamer, the bot calls the Twitch Helix API to register an EventSub subscription for the stream.online event on that channel.
- Twitch sends a signed HTTPS POST to TeraOne's webhook endpoint the moment the streamer goes live. The signature is verified to reject spoofed events.
- The payload is enqueued in BullMQ. A delivery worker resolves the template variables, builds the Discord message, and posts it to the configured channel.
- EventSub subscriptions are automatically renewed before they expire. Stale subscriptions (orphaned guilds, disabled module) are cleaned up nightly.
Privacy & data retention
The Twitch Notifications module stores only the metadata needed to deliver and log notifications. No stream content, chat messages, or viewer data is ever read or stored. The following categories are retained:
| Data type | Retention |
|---|---|
| Per-notification delivery log (status, timestamp, error) | 90 days |
| Raw EventSub payloads (stream title, game, started_at) | 365 days |
| Orphaned EventSub subscriptions (guild removed / module disabled) | Cleaned up within 30 days |
Automatic cleanup runs nightly. Older records are permanently deleted and cannot be recovered.
Troubleshooting
- History is empty after adding a streamer
- The history tab only fills when the streamer actually goes live after the subscription was created. If you want to verify the setup immediately, use the Test Preview button to send a simulated notification. If the test also fails, check that the bot has write permissions in the target channel.
- Role ping is not appearing in the notification
- Open the subscription editor and confirm roles are saved. Also check that the bot has the "Mention @everyone, @here, and All Roles" permission in the target channel — without it Discord silently strips the mention.
- "Streamer already added" error when trying to add a channel
- Each Twitch login can only be subscribed once per Discord server. If you want to send notifications to a second channel, edit the existing subscription and move the target channel, or remove the old subscription first.
Frequently asked questions
- How quickly does the notification arrive after the stream starts?
- Twitch pushes the event within seconds of the stream going live. End-to-end latency (Twitch event → Discord message) is typically 3–8 seconds.
- Can the same Twitch channel notify multiple Discord servers?
- Yes. Each Discord server has its own independent subscription. One Twitch channel can notify an unlimited number of servers simultaneously.
- What happens if the bot is briefly offline when a stream starts?
- Twitch retries EventSub delivery for up to 10 minutes after the initial push fails. If the bot comes back online within that window, the notification is delivered. Events older than 10 minutes are not replayed by Twitch.
- Can I get a notification when the stream ends?
- Stream-end (stream.offline) notifications are not yet supported in the dashboard UI but are on the roadmap. The underlying EventSub infrastructure already handles the event type.
- How many Twitch streamers can I add per server?
- Up to 25 Twitch subscriptions per Discord server.