TwitchLinkGuard - Block unwanted links

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:

:link: 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.
  • 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.

:ticket: Voucher-Code Detection

  • Automatic Promo-Code Spotting
    • Catches voucher codes, game keys, promo codes via regex.
      :busts_in_silhouette: Mention-Validation
  • Invalid-Mention Removal
    • Deletes messages that mention users not present in chat (excluding broadcaster/self).

:pencil: Exemptions

  • Whitelist Support
    • Domains or substrings that bypass all moderation checks.
  • Group-Based Rules
    • Allow Groups (e.g. TLG-TrustedUsers) handled in streamer.bot to bypass.
  • Temporary Exemptions
    • !permit <user> grants time-limited link-posting rights to a user.
  • Role-Based Exemptions
    • VIPs & Subscribers may optionally be exempt from specific filters.

:gear: Customization Options

  • Filter Customization
    • Define your own suspicious keywords & TLDs via commands or JSON.
  • Accurate Matching
    • Word-boundary checks to reduce false hits (e.g. “free” vs. “freezer”).
  • Custom Messages
    • Tailor replies for deletes, timeouts, bans, warnings, permits.
  • Appearance Controls
    • Choose bot vs. broadcaster account, text vs. /me actions.
  • Dynamic Settings
    • Update all parameters via arguments or JSON.
    • Your changes getting reflected in real-time.
  • Configurable Actions
    • timeout or ban based on your settings when something is detected. Messages always get deleted first.

:arrows_counterclockwise: 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.

Example:

ezgif.com-animated-gif-maker

TwitchLinkGuard may not work with alpha version of streamer.bot!

Import Files

TwitchLinkGuard-v2.0.sb (71.5 KB)
Hotfix: Hotfix for TLG - ..Config.. v2.2.sb (20.1 KB)
(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.

Basically that’s all you need to do to set up TwitchLinkGuard!



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 :smiley:

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.

Changelog:

v3.3

  • Merged Hotfix Hotfix for TLG - ..Config.. v2.2 seen in sb discord thread.
  • Updated default keywords of TLG - ObfuscationWatch to tackle newest spam messages.
  • Fixed a bug in TLG - ObfuscationWatch that 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.
Older Changelogs

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_NoRespondMessages that 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_HasReported that tells the user if the target is already reported.
  • Added a new message tlg_SomeoneElsePermit that 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.
    • !endpermit forces 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 & Whitelist now 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.
    :warning: However, since I still cannot test Channel Points myself, this is considered “WIP-Testing” :warning:
  • LinkInspector gives you the ability to check any URL (including obfuscated ones) for its legitimacy at any time.
    • LinkInspector clearly 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.
  • ObfuscationWatch is 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.
    • ObfuscationWatch independently 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 ...ExpirationsDays value.
    • 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 reportRoles to 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.
  • 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 Actions in the action TLG -..Config...
  • This Modular approach now makes a Light version obsolete, just disable what you don’t want to use without breaking anything. Only the action TLG -..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.

Seeing as the extension itself is more of in a “Testing” state at least looking at the Discord post and the amount of recent Changelogs, it might be best to first create a post in the “Testing” forums Testing - Streamer.bot Extensions, which should definitely be used before submissions if you know it’s not fully tested yet. That way you can also share the link from the testing forum with people outside, as the “Submission” forum is only visible for the people that created a topic and the staff :slight_smile:

1 Like

changed it to testing

1 Like