Events module
The Events module fires configurable rewards when Twitch events meet thresholds you define. Use it to celebrate community milestones, incentivise bits and gifted subs, run giveaways, and build cross-event reward chains — each earn is recorded, announced in chat, and tracked through a claim/complete fulfilment pipeline.
Requires the Affiliate tier or higher. See Module access by tier.
At a glance
| Capability | What it does |
|---|---|
| Reward rules | Ten trigger types (bits, tips, gifted subs, new sub, resub, chat phrase, follow, raid, channel points, meta) fire when a threshold is crossed |
| Rule actions | Post a templated chat message, an AI-generated message (Partner+), or grant giveaway entries |
| Events (windows) | Rules are grouped into events — time windows with optional goals; only one event is active at a time |
| Cumulative mode | Bits / gifted-subs thresholds apply to a viewer’s running total for the event, with retroactive backfill |
| Meta rules | Compound rewards that fire when a viewer has earned other rewards (Partner+) |
| Fulfilment pipeline | Every earn is a record you move through pending → claimed → completed, with notes and per-reward checklists |
| Manual grants | Grant any rule’s reward by hand for off-Twitch actions (donations, Throne, IRL) |
| Giveaways | Keyword and automatic entry methods, eligibility filters, weighted draws, claim windows, rerolls, and chat commands |
| Leaderboards & reports | Per-event top gifters/cheerers/tippers/resubbers, per-rule earn counts, top earners, plus Twitch’s lifetime gift totals for the channel (excludes anonymous gifts and gifters who hide their total) |
| Stream overlays | Event totals, recent rewards, goal progress, and counters exposed to the Widgets module |
How rewards fire
Every rule belongs to an event and fires only while that event is the channel’s active event. The core mechanics apply to all trigger types:
-
Threshold crossings. A rule fires once per threshold multiple. A 5,000-bit cheer against a 500-bit rule earns it 10 times; a cheer of exactly the threshold earns it once. The exception is raid, which earns at most once per qualifying raid regardless of size.
-
Multiple rules can match one event. A 5,000-bit cheer triggers both a “500 bits” rule and a “1,000 bits” rule.
-
Unlock lower rewards. When several bits, tips, gifted-subs, follow, or raid rules match the same event, the highest-threshold rule always fires and lower ones follow the Unlock Lower Rewards setting (each rule can override it). Three choices:
- Every time (default) — a lower rule is earned once per threshold crossing, so a $100 tip earns a $10 rule ten times.
- Once each — every lower rule still fires, but earns only once no matter how far the event overshot it: that same $100 tip earns the $10 rule once. Use this when a big cheer or tip is flooding your pending list with copies of a small reward.
- Not at all — only the highest matching rule fires.
“Once each” applies to any rule that has a larger rule above it in the same event, even when the event was too small to reach that larger rule — so a $50 tip can’t earn more copies of the $10 reward than a $100 tip does. A rule with nothing above it is never capped.
-
One chat message per rule per event. When a single cheer or gift earns a rule several times, each earn is recorded separately but the chat notification is collapsed into one message — use
$(reward_count)in the template to show how many times it fired. -
Earn caps. Each rule can set Max total earns (across all viewers) and Max earns per viewer; both default to unlimited. Once a cap is reached the rule stops earning.
-
Anonymous cheers and gifts still count toward channel totals and can earn rewards, but they can’t use cumulative mode and never trigger meta rules (there is no viewer to track).
Every earn is recorded as an earned reward with status pending and (optionally) announced in chat — see Earned rewards.
Events and the active event window
An event is a container for rules, typically matching a stream or a subathon. Create one in Events → Manage Events → New event with:
| Field | Limits |
|---|---|
| Event name | Required, up to 100 characters |
| Description | Optional, up to 500 characters |
| Event Goal (total rewards) | Optional, 1 – 1,000,000 |
| Start / End date-time | Optional; an event past its end time is disabled automatically (checked hourly) |
Only one event can be active at a time — enabling an event disables every other event on the channel. While no event is active, no rules fire at all. Rules are created inside an event and cannot move between events.
Per-event counters — follow counts, chat-phrase counts, per-viewer sub/resub counts, redemption counts, and cumulative bits/tip/gift totals — are scoped to the event. Starting a different event starts all of them from zero; the old event’s data is kept for its leaderboards and reports.
Event lifecycle actions (Lead Mod or broadcaster): Enable / Disable, Edit, Duplicate, Archive / Unarchive (unarchiving does not re-enable), Delete (removes the event and all of its rules), and Recalc — a repair action that recomputes cumulative totals from the stored transaction history and backfills any missed earns for bits and gifted-subs rules. Backfilled earns appear as pending rewards without posting to chat.
Duplicate copies an event’s settings and all of its rules under a new name. The start and end date-times are cleared, the copy is disabled and unarchived (so it appears in the normal Events list), and no earned rewards, transactions, cumulative totals or leaderboard data come with it — the copy starts from zero. Rules that your plan no longer allows (meta rules below Partner, or rules past your per-event limit) are skipped, and the confirmation says how many.
Trigger types
| Trigger | Fires when… | Threshold counts |
|---|---|---|
| Bits | A viewer cheers | Bits in a single cheer (or the viewer’s event running total in cumulative mode) |
| Tips | A viewer tips through the Tipping module | The amount of a single tip (or the viewer’s event running total in cumulative mode) |
| Gifted Subs | A viewer gifts subs | Subs in a single gift event, optionally tier-multiplied (or running total in cumulative mode) |
| New Subscribe | A viewer self-subscribes at the configured tier | That viewer’s new-sub count within the event |
| Resub | A viewer shares a resub message at the configured tier | That viewer’s resub count within the event |
| Chat Phrase | A viewer’s message matches a phrase | That viewer’s match count within the event |
| Follow | Anyone follows the channel | The channel-wide follow count within the event |
| Raid | An incoming raid meets a minimum viewer count | Single-shot — one earn per qualifying raid |
| Channel Points | A viewer redeems a specific channel-point reward | That viewer’s redemption count for the reward within the event |
| Meta (cross-rule) | A viewer’s earned rewards satisfy a cross-rule condition | See Meta rules |
A rule’s trigger type is fixed once created. Default threshold in the editor is 500. A rule can be duplicated within its own event — the copy carries every setting under a new name and starts disabled, so you can adjust it before it fires.
Bits
Counts channel.cheer events. Per-cheer by default; switch a rule to cumulative with the per-rule Cumulative bits/gifts setting (bits rules do not follow the global cumulative toggle — it is per-rule only).
Tips
Fires on settled tips from the Tipping module — your public tip page, manual tips recorded by hand, and positive goal adjustments all count. The threshold is entered in your channel’s tip currency (a 10 threshold means a $10 tip), and the rule fires once per multiple: a $100 tip against a $10 rule earns it ten times unless Unlock Lower Rewards caps it. Switch a rule to cumulative with Cumulative tips (this rule) to reward a viewer’s running tip total across the event instead.
Anonymous tips still fire non-cumulative rules, but — like anonymous cheers — they can’t accumulate a per-viewer total or feed meta rules, because there’s no viewer to track.
$(amount) renders a formatted currency string (“$25.00”), not a raw number. If a tip is later refunded or charged back, its earned rewards stay in your list with a funding reversed badge rather than disappearing — you decide whether to still honour them — and the viewer’s cumulative total is rolled back.
Gifted subs
Counts channel.subscription.gift events. With Tier Multipliers enabled in Settings, gifts are converted to points before the threshold check: Tier 2 gifts count ×2 and Tier 3 gifts ×5 by default (both multipliers are configurable). With multipliers off, one gift = one point. Cumulative mode follows the per-rule setting, falling back to the channel-wide Cumulative Gifts toggle.
New sub and resub
Both are tier-specific: a rule fires only for subs at its configured Subscription tier (Tier 1, 2, or 3). Twitch reports a subscription in two stages — a subscribe event and, for renewals, a resub message — so the module guards against double counting: a subscription later confirmed as a resub has its erroneous new-sub earn rolled back and is re-counted as a resub. Counts are per viewer per event, so a “Resubs needed: 1” rule rewards each sharing resubber once per event.
Count Twitch Prime (global and per-rule) lets you exclude Prime subs from firing Tier 1 rules. Twitch’s subscribe events don’t say whether a sub is Prime — only the chat sub notice does — so Events listens for those notices and remembers who is Prime. If the notice arrives moments after the sub was already counted, the earn is corrected retroactively (rows are removed; any chat message already sent is not retracted). Prime detection needs the chat-notice permission — the Events page will prompt you to re-authorise if it’s missing.
Chat phrase
Matches each viewer’s messages against the rule’s Chat phrase (up to 200 characters) with a Match mode of contains (default), starts_with, or exact, case-insensitive unless Case sensitive is on. The rule fires each time a viewer’s personal match count crosses a multiple of the threshold — e.g. threshold 5 rewards a viewer on their 5th, 10th, 15th… matching message in the event.
Follow
A channel-wide milestone counter: the rule fires each time the event’s total follow count crosses a multiple of the threshold, and the viewer whose follow crossed the line earns the reward. “Every 100 followers” is a single rule with threshold 100.
Raid
Fires when an incoming raid brings at least the threshold’s viewer count. The raiding broadcaster earns the reward, once per qualifying raid — a huge raid does not multiply the earn. The raid’s viewer count is available as $(viewers) in the message template.
Channel point redemption
Pick one of your channel’s custom rewards from the Channel point reward dropdown (loaded live from Twitch). The rule counts each viewer’s redemptions of that reward within the event and fires on threshold multiples — set Redemption count per viewer to 1 for every redemption, or higher for loyalty-style rewards (“redeem 10 times”). An optional Max triggers per hour rate-limits the rule; while limited, redemptions still count but the rule doesn’t fire. Deduplication guarantees a redemption is processed once even if another module also subscribes to redemptions.
Rule actions
Each rule performs one Action when it fires:
- Plain message — a chat message from the template below.
- AI-generated message — Workers AI composes a fresh message from your prompt (Partner tier and above).
- Grant giveaway entries — no chat message; grants entries to the active or next giveaway (see Giveaways).
Message templates
Templates are up to 500 characters. Substitution variables depend on the trigger:
| Variable | Value | Available for |
|---|---|---|
$(username) (alias $(user)) | Viewer’s display name | All triggers |
$(amount) (alias $(count)) | The trigger amount — bits cheered, subs gifted, resub months, viewer’s phrase/sub/redemption count, event follow total | All triggers |
$(tier) | Subscription tier (Tier 1/2/3) | Gifted subs, new sub, resub |
$(months) | Total months subscribed | Resub |
$(streak) | Current streak months | Resub |
$(reward_count) | How many times this rule fired for this event notification | Bits, gifted subs |
$(viewers) | Raid viewer count | Raid |
The editor warns about emote-like words that aren’t in your channel’s emote set and includes a browser to insert real channel emotes.
AI-generated messages (Partner and above)
Set the action to AI-generated message and write a system prompt (up to 2,000 characters) describing the voice and lore to draw on. When the rule fires, the AI receives the viewer’s name and what they did (e.g. “cheered 1500 bits”), plus up to 50 of your channel’s emote names so it can use them naturally. Output is capped at 500 characters.
AI messages consume your channel’s daily AI token allowance (shared with the AI module; see Tier comparison). If the allowance is exhausted, the channel is below Partner tier, or generation fails, no message is sent — there is no fallback to a plain template, so keep at least one plain-message rule for must-announce milestones.
Cumulative mode
Bits and gifted-subs rules can apply their threshold to a viewer’s running total for the event instead of a single cheer or gift. A 1,000-bit cumulative rule rewards a viewer who cheers 400 + 400 + 200 across the stream. Totals are per event — a new event starts everyone at zero.
Turning cumulative on for an existing rule (or enabling the channel-wide Cumulative Gifts toggle) triggers a backfill: totals are recomputed from the event’s recorded cheer/gift history and rewards are retroactively created for viewers who already crossed the threshold, respecting the rule’s earn caps. Retroactive earns arrive as pending rewards without a chat announcement.
Anonymous cheers and gifts are excluded from cumulative totals.
Meta rules
A meta rule (Partner tier and above) fires when a viewer’s other earned rewards in the same event satisfy a condition:
- All-of — the viewer has earned every rule in the Source rules list at least once.
- Any-count — the viewer has earned at least N rewards from the source list; with an empty list, from any rule in the event (the meta rule’s own earns don’t count toward itself).
Meta rules are evaluated after every recorded earn — including manual grants and other meta earns — and chain recursively up to four levels deep, so a meta can unlock another meta. Earn caps apply to meta rules like any other rule. Anonymous earns never trigger meta evaluation.
Earned rewards and fulfilment
Every earn creates a record on the event’s Pending Rewards tab with status pending. Move it through the pipeline with per-row actions:
| Status | Meaning | Transition |
|---|---|---|
pending | Earned, not yet actioned | → Claim |
claimed | The viewer has claimed it | → Complete |
completed | Fulfilled | → Reopen (back to pending) |
Each reward supports a free-text note (up to 1,000 characters) and a per-reward checklist for multi-step fulfilment. Optional chat announcements fire on claim and complete, using templates with $(username) and $(reward):
- Claim default:
$(username) just claimed their $(reward) reward! - Complete default:
$(username)'s $(reward) reward has been completed!
Both are off by default (Chat on Claim / Chat on Complete in Settings, overridable per rule with custom messages).
Manual grants
Tips taken through the Tipping module fire Tips rules automatically, but Twitch doesn’t deliver third-party donations (StreamLabs, StreamElements, Ko-fi) or Throne purchases over EventSub, so those can’t. Instead, the broadcaster or a Lead Mod can use Grant manually on the Pending Rewards tab: pick a rule, enter the viewer’s Twitch username (validated against Twitch) and — for bits/gifted-subs rules — an amount and tier. The grant earns the rule once per threshold multiple (⌊amount ÷ threshold⌋, tier multipliers included, capped at 1,000 earns per grant) and flows through the normal pipeline: chat notification, meta-rule evaluation, and earn caps all apply. An optional reason field records the source.
Giveaways
Run giveaways from Events → Giveaways. One giveaway is active at a time; end the current one before opening another.
Opening a giveaway
| Option | Behaviour |
|---|---|
| Giveaway name | Optional label, up to 200 characters |
| Eligibility filter | anyone (default), followers only, subscribers only, Tier 1+/Tier 2+/Tier 3 only, or VIPs only — checked live against Twitch at entry |
| Require claim | Winner must type !claim within the claim window or is disqualified |
| Claim window | 30 – 3,600 seconds, default 300 |
| Revalidate at draw | Re-check each entrant’s eligibility at draw time (entries earned through reward rules skip revalidation) |
| Allow multiple entries | Viewers accumulate entries instead of one each; draws are weighted by entry count |
| Event Reward Only | Restricts entry to viewers who earned a reward in a chosen event (disables all other entry methods and backfills entries from that event’s earns) |
| Time limit | Optional expiry, set as a duration or as an end time — entries close automatically when it runs out. Not available for Event Reward Only giveaways |
Entry methods
Entry methods are chosen when the giveaway opens and locked once it starts:
| Method | Options |
|---|---|
| Keyword | Viewers type the exact keyword (up to 100 characters, case-insensitive) in chat |
| Bits | Minimum bits required, bits per entry, entries per trigger |
| Subscribe | Minimum tier, entries per sub |
| Gifted Subs | Minimum gifts required, gifts per entry, entries per trigger |
| Channel Points | Optional reward ID to match, entries per redemption |
| Reward rules | Any rule with the Grant giveaway entries action feeds its entries to the active or next giveaway |
Entries targeted at the next giveaway (from reward rules, or earned while no giveaway is open) are held as pending entries for up to 14 days and flushed in automatically when the next giveaway opens.
Time limit
A giveaway can be given an optional time limit when it opens — either a duration (1 minute to 30 days from now) or an absolute end time. Chat announces the limit alongside the giveaway, then posts countdown reminders on the way down (a longer giveaway gets coarser reminders; a very short one gets few or none).
When the limit runs out, entries close automatically and chat is told, exactly as if a mod had pressed Close entries. If Draw a winner automatically was switched on, a winner is drawn and announced in the same moment — with Require claim on, that starts the usual claim window. Leave it off and the giveaway simply stops taking entries, so you can draw whenever you’re ready.
Closing, picking or ending the giveaway yourself before the limit cancels it. A time limit is not available for Event Reward Only giveaways, and the !giveaway open chat command doesn’t take one — set it from the dashboard.
Drawing and claiming
Pick winner draws randomly, weighted by entry count. If Require claim is on, the winner is announced and must type !claim in chat within the claim window; unclaimed wins are disqualified automatically and the giveaway reopens for a redraw. Reroll disqualifies the current winner and draws again. End giveaway closes everything out. All transitions are announced in chat.
Giveaway chat commands
Moderators and the broadcaster can drive giveaways from chat:
| Command | Effect |
|---|---|
!giveaway open <keyword> | Open a keyword giveaway |
!giveaway close | Close entries (draw still possible) |
!giveaway pick | Draw a winner |
!giveaway reroll | Disqualify the current winner and redraw |
!giveaway end | End the giveaway |
!claim | (Winner only) claim within the claim window |
Entrant limits are tier-based: 1,000 entrants on Affiliate, 10,000 on Partner and above. See Tier comparison.
Chat behaviour and safety rules
- Announcements are posted as the broadcaster (this module does not use the shared/custom bot identity — that applies to Chatters and Modomation).
- Earn messages are paced ~2 seconds apart. During large bursts, the first 5 messages send immediately and the rest are queued and drained over the following minutes — earn announcements from a big gift bomb trickle out rather than flooding chat.
- All chat messages are truncated to 500 characters, and sends are rate-limited to 20 per minute per channel.
- Incoming Twitch events are deduplicated for 24 hours, so webhook redeliveries never double-earn.
- If a chat send fails, the earn is still recorded — the reward appears in Pending Rewards even when the announcement didn’t go out.
Stream overlays
Event data — running totals for gifted subs and bits, recent rewards, top gifters/cheerers, goal progress, and single-stat counters — is exposed to OBS browser sources through a per-channel widget token (a 64-character key; revoking it invalidates every running overlay). Overlay setup lives in the Widgets module; the retired Events → Widgets tab redirects there.
The Event Page’s browser source (above) is a second overlay surface — the same event, rendered for OBS from the Broadcaster view pane.
The public Event Page
Events → Event Page gives the channel a public page at
streamercatalyst.com/e/<your-twitch-name> — a link to drop in chat that shows the
night as it happens: the subathon clock, the goals ladder, what viewers can earn,
the open giveaway, the wheel, the leaderboards and the tip goal. It refreshes
itself every 30 seconds, so a viewer can leave it open.
The tab has two panes, and each carries its own style, its own card list and its own live preview.
Public page is what viewers see, and it starts off. The page is private until you turn Publish this page on: before that the link answers “not published” to everyone but you, so you can lay it out, style it and preview it first. Turning the toggle back off takes it down again — the link stops working for viewers immediately, and nothing about your event is exposed while it is off. Headline replaces your channel name at the top of the page.
Broadcaster view is the same event rendered bare for OBS: no navigation, no sign-in, no footer — a ring clock, the goals as a milestone track, and four stat tiles. Copy the browser-source URL into an OBS Browser source at 1920×1080. That URL carries your overlay token, so it is broadcaster and Lead Mod only, and revoking the token in the Widgets module invalidates it. It is not affected by the Publish toggle — that switch governs the public page only, so your own overlay keeps working whether or not viewers can reach the page.
Style
Both panes use the same controls as the Widgets Style tab: six accent presets plus a colour well and a hex field, a background theme, a font, a font colour (Auto follows the theme), and Base Size / Font Size sliders. The public page has Dark and Light; the browser source adds Transparent, which drops every surface so it composites over your scene. The preview is the real page — not a mock-up — so what you see is what it renders.
Cards
Drag to reorder, or use the arrows; the toggle turns a card off. The order is the order viewers scroll through.
A card with nothing behind it is left out entirely. A channel with no subathon widget gets no clock; a channel with no wheelspin gets no wheel. And a figure we could not read is shown as an em dash with a sentence saying so — never as a zero, because “nobody cheered tonight” and “we could not reach the service that counts cheers” are different things.
The stat strip says which window each figure covers: subs, bits, gifted subs and new follows are this stream (the one running now, or the last one that ended), while rewards earned is this event. They are two different scopes and the labels keep them apart.
Viewer sign-in
A viewer can sign in with Twitch to see their night: their entries in the current giveaway, what they have given this event, and where they sit among the event’s cheerers. Between events there is no window to measure “what you gave” against, so those figures are withheld rather than widened to a lifetime total — the panel says so. It asks for no permissions at all — the name is the whole point of it, nothing is posted on anyone’s behalf, and no viewer account is created. The identity is a signed cookie scoped to the Event Page and nothing else, and it expires on its own after 30 days.
Signed-out viewers see everything except that one panel.
Setup and EventSub
Bits and gifted-subs subscriptions are registered for every channel. Follow, chat, channel-points, new-sub, resub, and raid subscriptions are created only when an enabled rule of that trigger exists — the Manage Events page shows a warning banner when enabled rules are missing their subscription, with a Run setup button to register them and a Re-authorise link if Twitch permissions are missing.
See Events — Authentication & permissions for the OAuth scopes and EventSub subscription details.
Roles and permissions
- Broadcaster and Lead Mods can do everything: manage events, rules, giveaways, rewards, settings, and manual grants.
- Regular mods have read access and can work the Pending Rewards pipeline, but cannot create or edit events, rules, giveaways, or settings.
- Read-only masquerade sessions cannot change anything.
- The Event Page’s browser-source URL is broadcaster and Lead Mod only: it carries the channel’s overlay token. Regular mods see the rest of the pane.
Settings reference
Events → Settings (defaults in parentheses):
| Setting | Effect |
|---|---|
| Enable Events (off) | Master switch for the module on this channel |
| Tier Multipliers (off) | Convert gifted subs to points: Tier 2 ×2, Tier 3 ×5 (both configurable) |
| Cumulative Gifts (off) | Channel-wide default for gifted-subs rules without a per-rule cumulative setting |
| Count Twitch Prime (on) | Count Prime subs toward Tier 1 rules; off excludes them (detected via chat sub notices) |
| Unlock Lower Rewards (Every time) | What lower-threshold matching rules do: fire on every time they’re crossed, once each per event, or not at all |
| Chat on Earn (on) | Announce earns in chat |
| Chat on Claim (off) / Chat on Complete (off) | Announce status changes, with editable templates |
Most of these can be overridden per rule in the rule editor’s Advanced settings.
Tier availability
| Feature | Affiliate | Partner / Partner+ |
|---|---|---|
| Events module | ✓ | ✓ |
| Rules per event | 5 | Unlimited |
| AI-generated messages | — | ✓ |
| Meta rules | — | ✓ |
| Giveaways | ✓ (1,000 entrants) | ✓ (10,000 entrants) |
See Tier comparison for the full matrix.
Example rule ideas
| Idea | How |
|---|---|
| Bits ladder | Three Bits rules at 500 / 1,000 / 5,000 with escalating rewards; leave Unlock Lower Rewards on “Every time” so a 5,000 cheer earns all three |
| Tip ladder without the spam | Tip rules at $10 / $50 / $100; set Unlock Lower Rewards to “Once each” so a $100 tip earns one of each instead of ten $10 rewards |
| Sub-a-thon milestone | Follow rule, threshold 100: ”🎉 $(username) was our 100th new follower of the event!” |
| Community gift chase | Cumulative gifted-subs rule at 20: ”$(username) has gifted $(amount) subs this stream — legend!” |
| Loyalty redemption | Channel-points rule, threshold 10: reward a viewer’s 10th redemption of a hydrate reward |
| Raid welcome | Raid rule, threshold 10, AI message prompted to welcome the raider by name and viewer count |
| Hype phrase counter | Chat-phrase rule on your channel catchphrase, threshold 25, contains-match |
| Super-fan badge | Meta all-of rule over a Bits rule + a Gifted Subs rule + a Resub rule — fires only for viewers who did all three |
| Giveaway feeder | Bits rule with the Grant giveaway entries action so every 100 bits adds an entry to the next giveaway |
See Inspiration / recipes for cross-module automations that build on these rules.
API and endpoint reference
See Events — API endpoints for the full list of HTTP endpoints.
Auth reference
See Events — Authentication & permissions for the OAuth scopes this module uses and the EventSub subscriptions it registers.
Share Feedback
Need help or want to chat? Join our Discord to get support, report bugs, and talk with other streamers.▸ What we're sending
| Module | — |
| Page | — |
| Browser | — |
| Screen | — |
| Channel | anonymous |
| Submitted | — |