Cooldowns & Rate Limiting
Cooldowns prevent the same alert from firing too frequently. This is useful during raids, gift bomb events, or whenever you want to avoid overlapping alerts or device actions.
Each alert can have its own cooldown settings, independent of other alerts.
Why Use Cooldowns?
Without cooldowns, every matching event fires the alert immediately. During a gift bomb (50 gifted subs in 10 seconds), that means 50 simultaneous overlay animations, 50 Discord messages, and 50 device triggers.
Cooldowns let you say: "Fire this alert at most once every 30 seconds" or "each viewer can trigger this at most once per minute."
Cooldown Types
Global Cooldown
A global cooldown applies to the entire alert, regardless of who triggers it.
- Once the alert fires, it will not fire again until the cooldown expires.
- Example: "Only show this overlay once every 10 seconds, no matter how many events arrive."
Per-User Cooldown
A per-user cooldown tracks each viewer individually.
- Each viewer has their own cooldown timer for this alert.
- Once a viewer triggers the alert, they cannot trigger it again until their personal cooldown expires.
- Other viewers are unaffected.
- Example: "Each person can trigger the PiShock action at most once per 60 seconds."
You can use both cooldown types on the same alert. For example: each user is limited to once per 30 seconds, AND the alert can fire at most once every 5 seconds globally.
Cooldown Behaviour: Ignore vs. Queue
When a cooldown is active and a new event matches the alert, TipLink can handle it in two ways:
| Mode | What happens |
|---|---|
| Ignore | The event is skipped entirely. Nothing fires. The event is still recorded in Activity. |
| Queue | The event waits until the cooldown expires, then fires automatically. |
Choose Ignore when you want to strictly limit how often the alert fires (e.g. device actions where stacking could cause harm).
Choose Queue when you want to ensure every event eventually fires, just spread out over time (e.g. overlay animations).
Configuring Cooldowns
- Open or create an Alert.
- Scroll to the Rate Limiting section.
- Enable the Rate Limiting toggle to expand the settings.
- Configure the options you want:
Global Cooldown Settings
| Setting | Description |
|---|---|
| Enable Global Cooldown | Turn the global cooldown on or off |
| Global Cooldown (seconds) | How long to wait before the alert can fire again |
Per-User Cooldown Settings
| Setting | Description |
|---|---|
| Enable Per-User Cooldown | Turn per-user cooldown on or off |
| Per-User Cooldown (seconds) | How long each individual viewer must wait before triggering again |
Behaviour
| Setting | Description |
|---|---|
| Rate Limit Behaviour | Choose Ignore or Queue for how events are handled during cooldown |
Advanced Mode
When Advanced Mode is enabled on an alert, you can also set per-action cooldowns. This lets individual actions within an alert have their own cooldown separate from the alert-level cooldown.
For example: the Stream Overlay action fires every time, but the PiShock action only fires once every 60 seconds — all within the same alert.
Tips
- Start with a 5–10 second global cooldown on visual overlay alerts to prevent overlapping animations.
- Use a 60-second per-user cooldown on device actions to prevent a single viewer from spamming triggers.
- Use Queue mode for overlay alerts (so every donation gets acknowledged) and Ignore mode for device actions (to prevent stacking).
- Cooldown timers persist through TipLink restarts — if you restart TipLink mid-cooldown, the cooldown continues.