TwitchLinkGuard - Block unwanted links
TwitchLinkGuard is designed to help Twitch streamers and moderators maintain a safe and clean chat environment. TLG is a comprehensive tool for automated moderation, making it an essential solution for Twitch streamers looking to enhance and streamline their chat moderation.
Key Features:
Detection & Filtering
- URL Pattern Detection
- Auto-detects standard URLs and removes/flags harmful links.
- Obfuscation Detection
- Recognizes disguised links like
example [dot] com,ex·ample.com,exam ple .com, etc.
- Recognizes disguised links like
- Blacklist Enforcement
- Only broadcaster & mods may post blacklisted domains/URLs; all others are auto-blocked.
- Failure-Safe Behavior
- Ignores URL-like text that isn’t a true link (e.g.
hi.how,oh…my) to minimize false positives.
- Ignores URL-like text that isn’t a true link (e.g.
- Accurate Matching
- Word-boundary checks to reduce false hits (e.g. “free” vs. “freezer”).
Voucher-Code Detection
- Automatic Promo-Code Spotting
- Catches various types of voucher codes, game keys, promo codes via regex.
Mention-Validation
- Invalid-Mention Removal
- Deletes flagged suspicious messages that mention users which not exist.
- Ignores mentioning existing users not present in chat.
Exemptions
- Whitelist Support
- Domains, words or substrings that bypass all moderation checks.
- Group-Based Rules
- Allow Groups (e.g.
TLG-TrustedUsers) handled in streamer.bot to bypass all moderation checks permanently.
- Allow Groups (e.g.
- Temporary Exemptions
!permit <user>grants time-limited rights to skip all moderation checks.
- Role-Based Exemptions
- VIPs & subscribers can be optionally excluded from moderation separately and permanently.
Customization Options
- Filter Customization
- Define your own suspicious keywords & TLDs via commands or JSON.
- Custom Messages
- Tailor replies for deletes, timeouts, bans, warnings, permits.
- Appearance Controls
- Choose bot over broadcaster account and fallback automatically if needed.
- Use normal text or this cursive style for messages.
- Dynamic Settings
- Update all parameters via arguments or JSON.
- Most important changes getting reflected in real-time.
- Configurable Actions
- timeout or ban based on your settings when something is detected. Messages always get deleted first.
- Define the length for timeouts individually for each action.
Automations & Learning
- Recurring-Message Learning
- Tracks repeated spam patterns and auto-adds new keywords/TLDs for future detection.
- Auto-Handling of Known Harm
- Integrates with Twitch’s built-in link filters to enforce your chosen action.
- Check URL Infection
- Use
!checklink <url>to send a normal or obfuscated url to e.g. VirusTotal to check if a link is potentially harmful.
- Use
Reports
- Unique Report Feature
- Trusted users/groups can report users if the misbehave in chat.
- If a user is succesfully reported, a ban or timeout happens, based on your settings.
- Misuse Prevention
- Each report is unique from a user. This way, one user can’t spam reports for other users to get them punished rapidly. Multiple user must report the same user to trigger further actions.
- If a user is not sufficiently reported within 1 hour, all reports are discarded.
Link Safety Check
- Check URLs before using them
- You can send URLs to e.g. VirusTotal to let them scan if they are safe to use.
- You can check legit and obfuscated URLs.
- Handles infected URLs
- If the API returns a detected infection, the URL gets deleted from chat automatically.
- Caches results
- Results get cached to prevent API spam and running out of free calls.
Example:
TwitchLinkGuard may not work with alpha version of streamer.bot!
Import Files
TwitchLinkGauard 2.0 v3.5.sb (77.5 KB)
(Full script always contains all latest hotfixes)
Hotfix:
(Hotfix always contains just the mentioned specific action
Install TwitchLinkGuard
Step 1 - Import
In Streamer.bot click the Import button in the top menu. Drag the .sb file into the Import String field.
Step 2 - Commands
Enable the command in the Commands tab.
Step 3 - Actions
You now have multiple actions you can use or disable. Keep in mind that the TLG - ..Config.. always has to be Enabled for the other actions!
Step4 - Sub-Actions
As you can see, all usable sub-actions are now gathered in the new TLG - ..Config.. action that works like a “control center”. It feeds JSONS that again populate your settings as GlobalVar.
The sub-actions are grouped according to their corresponding action, so you can find your settings easily. Notable mention is Exempt & Enforce for Actions which collects all sub-actions that take care for exemptions like whitelists and blacklists and are kind of important if you want to explicitly allow or disallow URLs to be used in chat.
Step 5 - Editing Messages (Optional)
If you’re updating from an older version, you should backup your files because the new version config might differ from the old one, as well as the messages.json
You might want to edit, translate or correct some messages, you can find them in the root-folder of streamer.bot in the newly created TwitchLinkGuard folder.
twitchlinkguard-messages.json contains all messages that are used by any action of TLG. They are logically grouped for easy editing.
Disclaimer:
TwitchLinkGuard was collaboratively developed with community contributions and assisted by AI (ChatGPT & Gemini). It is provided “as-is” but i will try to help as good as i can.
Explanations to Features
LinkInspector
Sometimes you will receive links from users you would trust at first glance, but you’re unsure if this link is really “safe” to use. Now you can check those links!
Installation
All you need to do is, set up a free VirusTotal, URLHaus or urlscan.io account:
VirusTotal, https://auth.abuse.ch/, Login - urlscan.io
And paste your API-Key into the LinkInspector sub-action group of the TLG - ..Config.. action.
Usage
Enter !checklink <url> in chat and your provided url will be processed if it is safe or unsafe.
ReportRadar
Doing a Subathon stream and your mods are already sleeping? Your VIPs, Subs or a specific group in streamer.bot can work together to report unwanted users in your chat! After sufficient reports, a user will be punished according to your settings
Installation
All you need to do is, editing the sub-actions to fit your needs
You can decide who is able to report, manage groups which are protected from being reported (in the sub-action group Exempt & Enforce for Actions of the TLG - ..Config.. action) and decide the punishment.
Usage
Use !report <targetUser> <reason> to report a user. The <reason> added to the report, will be added to the final message when the reported targetUser get punished.
You can also report multiple users at once with !report <targetUser1,targetUser2,targetUser3,...> <reason>
Each report is unique, a user can’t report another user multiple times to punish someone rapidly. In default settings, 3 different users must report the same user in 1 hour to succesfully start further actions.
Link Permit
This is probably the only action that was nearly left untouched besides some code cleanup. Also there was for now WIP option added for users, to use channel points to give themselve a timed permit.
If %tlg_PermitUseCP% = true, the command still works. To edit the %tlg_timeLabels% just edit each word coming after = e.g.: minutes=Minuten.
Usage
To permit a user, type !permit <targetUser> in chat.
ObfuscationWatch
Detecting spam like “cheap viewers…”, etc. was always one of the goals of TwitchLinkGuard and is now separated from the main script to have the ability of a more focused approach to achieve this goal.
Since the old TLG v5 this system got somewhat of self-maintaining and learn new words by itself and removes them if they are unseend for a certain period of days.
You can define certain thresholds and you can disable features if there are issues in the corresponding sub-action group in the TLG - ..Config.. action.
It’s possible now for moderators to check, add and remove manually keywords & endings (TLDs) to the list as “non-standard” arguments.
Usage:
!addkeyword <argument> = add single or multiple keywords to the list.
!removekeyword <argument> = remove single or multiple keywords to the list.
!listkeywords <argument> = get a list of all manually or learned keywords in chat.
!addending <argument> = add single or multiple endings (TLDs) to the list.
!removeending <argument> = remove single or multiple endings (TLDs) to the list.
!listendings <argument> = get a list of all manually or learned endings (TLDs) in chat.
TwitchLinkGuard & TwitchWarn
The Core TLG Script now follows a completely different approach by just deleting messages instead of directly ban/timeout a user. Since twitch started to do some sort of “advertising-friendly” check in the background against broadcasters to “rate” them for being advertiser friendly or not. Prolly everything is counted in, banning new users in chat, timeout the same user rapidly for seemingly no reason or doing other stuff that seems weird for twitch. In worst case, twitch will shoot your channel into the void with a shadowban for a month and completely stops promoting your channel in any way. Happened to me after starting creating TLG 
The biggest change to the old TLG is, that you don’t have to maintain separate lists anymore and it uses external lists to check if a link is malicious or not. All links will be deleted in general if not whitelisted or the user is exempt for any reason but a ban/timout now only happens if the detected URL is an exact match of a known malicious source. Typos like "Hey.you" or similar are still ignored as always.
Twitch Warn has now actual meaning, after a defined threshold of warns a user get either banned/timed out. To activate this has also a second positive influence for all moderators because warns are tracked in the users history which makes it easier to track down if a user has a record of chat violations.
Light Version
Due to the new modularity of TwitchLinkGuard, a Light Version is now obsolete. Just disable what you don’t need. Only TLG - ..Config.. must stay Enabled all the time.
Disclaimer:
TwitchLinkGuard was collaboratively developed with community contributions and assisted by AI (ChatGPT & Gemini). It is provided “as-is” but i will try to help as good as i can.
Changelogs:
Regular Updates
v3.5
- Added a new action:
TLG - AutoMod & Restricted- With this action, you can now handle messages held back by twitch automod. Define the minimum level on which the automod should deny messages automatically and for which categories.
- WIP - Filters messages from users that are already flagged as “restricted” by twitch.
- Updated
TLG - ..Config..to v2.3- Updated triggers.
- Added a new group
AutoMod & Restrictedfor the new action including new args.tlg_AutoDenyMessagesto disable the feature if there are issues.tlg_RestricedUserssame as above.tlg_MinAutoModLevelToDenydefine the minimum level the automod should deny any message automaticallytlg_AutoDenyCategoriesdefine the category that are used. (There exist already a wide range of categories, you may want to edit the value first)
- Added new args to the
twitchlinkguard-config.json.
- Updated
TLG - ObfuscationWatchto v2.5- Now also detect if a mentioned user exist but is not present.
- Log spam should be now at a minimum in general for TLG
Hotfixes
No available hotfixes.
Older Changelogs
Regular Updates
v3.4
- Merged Hotfix for TLG - ReportRadar v3.1 seen in sb discord thread.
- Merged Hotfix for TLG - ObfuscationWatch v2.4 seen in sb discord thread.
Hotfixes
Hotfix for TLG - ObfuscationWatch v2.4
- Fixed a typo that caused that the spam indicator stopped working
- Updated default keywords of
TLG - ObfuscationWatchto tackle newest spam messages. - Word boundary regex is now more strict to scan for exact words and exclude variations.
- Removed an unused trigger.
Hotfix for TLG - ReportRadar v3.1
- Changed some parameters for
TLG - ReportRadar. Also stopped throwing helix errors in log for no reason. - Edited the Log-Level on some cases to stop spamming the logs for no reason.
v3.3
- Merged Hotfix Hotfix for TLG - ..Config.. v2.2 seen in sb discord thread.
- Updated default keywords of
TLG - ObfuscationWatchto tackle newest spam messages. - Fixed a bug in
TLG - ObfuscationWatchthat prevented using commands to add/remove keywords or endings. - Changed some parameters for
TLG - ReportRadar. Also stopped throwing helix errors in log for no reason. - Updated some messages in the messages.json to be more eye catching.
Bugfix for TLG - ..Config.. v.2.1
- Implemented a timer to run Init() every 60 seconds. That should be enough to cover all occasions.
Hotfixes include only the minimal, targeted configuration changes and omit any extra actions or commands. See TwitchLinkGuard-v2.0.sb for the full project import.
v3.2
- You can now use commands to add objects to the whitelist and blacklist in chat with
!addwhitelist,!addblacklist,!removewhitelist,!removeblacklist. Therefore, the corresponding args are now disabled by default since they would always overwrite everything done with the commands. - Merged Hotfix v3.1 which brought UTF-8 language support.
- Updated some comments
- Changed a trigger of
TLG - ..Config..to a timer, that should also prevent some unnecessary errors in the logs.
Latest available hotfix only contains the updated TLG - ..Config.. action.
TLG - ..Config..now uses UTF-8 to fully support the use of messages in kyrillic, latin, ascii languages.
Thx for pointing it out @tomo92s
This is just a hotfix for TLG - ..Config.. the hotfix import does not contain anything else. Please see the Opener for the full script.
v3
TLG- ..Config..
- Added a new argument
tlg_NoRespondMessagesthat makes it easier if you don’t want to have any respond message for ban/timeout/message delete in general. - Added a new message
tlg_HasReportedthat tells the user if the target is already reported. - Added a new message
tlg_SomeoneElsePermitthat tells the user who has already a permit. - Generally, unified the look of the args to be consistent upper case after “tlg_”
- Removed some left over code from previous versions.
- Renamed the JSONS groups to reflect the name change of the actions
TLG - Link Permit
- Reworked the script to now use actual commands.
- Available commands:
!permit <user>same as before but is handled in the commands tab of sb.!endpermitforces to end the current running permit.
TLG - LinkInspector
- Reworked the script to now use actual commands.
- Available commands:
!checklink <url>functionality stays the same.
TLG - ReportRadar
- Reworked the script to now use additionally commands.
- Available commands:
!report <user1,user2,...>functionality stays the same.
TLG - TwitchLinkGuard & TwitchWarn
- Added a logic that should prevent the script from deleting messages containing emojis in rare occasions
v2
- All arguments are now bundled by the new action
TLG -..Config..and are grouped according to the actions to which they belong.Blacklist&Whitelistnow work reliably, even with special characters like german umlauts.- All args feed JSONs which are then populated as GlobalVars in Streamer.bot, accessible by all actions. This step was taken in the hope of making it easier to implement a GUI later.
- A timestamp was added to the JSONs to track when they were last updated by the script. (Manual inputs are not considered by the timestamp)
- For
Link Permit, a Channel Points function was added that allows users to grant themselves a permit for a specified period.
However, since I still cannot test Channel Points myself, this is considered “WIP-Testing” LinkInspectorgives you the ability to check any URL (including obfuscated ones) for its legitimacy at any time.LinkInspectorclearly warns you about dangerous links and removes them.- Three different API providers (including VirusTotal) are used, with attention to making it easy for you to get your own API key for free. (Links to the APIs are in the sub-action comments). Of course, you don’t have to use all three, but VirusTotal is recommended.
ObfuscationWatchis the action separated and reintroduced from the main script that filters typical Twitch spam (e.g., “cheap viewers..”, “your chat is snoring…”).- Args were introduced to disable specific features if problems occur.
ObfuscationWatchindependently learns new keywords and endings if spam patterns slightly change and also removes keywords/endings if they have not appeared for a defined period, keeping the list as current as possible.- Commands were introduced allowing moderators to manually add or remove keywords/endings.
- Available commands:
!addkeyword <argument>,!addending <argument>,!removekeyword <argument>,!removeending <argument>. - Keywords/Endings added this way are automatically “non-default” and are removed if they are no longer seen according to the
...ExpirationsDaysvalue. - Successfully tested multiple times: Messages like “cheap viewers…” that Twitch already blocks were successfully deleted.
- Community Report Users was renamed to
ReportRadar.- It is now possible to specify a single group as
reportRolesto restrict this function to specific users. - Moderators, broadcasters, and the bot should now reliably not be able to report each other or be reported by others.
- It is now possible to specify a single group as
- Main Script was renamed to
TwitchLinkGuard & TwitchWarn.- Public lists are used to scan URLs for potential danger; if a link is an exact match from a list, the corresponding user is proactively timed out or banned according to the settings.
- All exceptions as well as whitelist/blacklist were bundled in the group
Exempt & Enforce for Actionsin the actionTLG -..Config... - This Modular approach now makes a
Lightversion obsolete, just disable what you don’t want to use without breaking anything. Only the actionTLG -..Config..itself must stay active. - Possibly more that I forgot to remember.
Hot- & Bugfixes separately followed after releasing TLG 2.0 v2 in discord are already implemented in this release here.
