The Chat Filter addon is a very powerful tool introduced in version 5.2.3 of Textual which uses the technology known as regular expression to create "filters" which search incoming plain text messages for a specific value. When the Chat Filter addon matches an incoming message against an existing filter, it is capable of performing one or more actions:
- Hide the message from appearing in the chat view
- Automatically perform any combination of commands in response to the message
- Forward a copy of the original message to another window (query)
This knowledge base article acts as a tutorial for creating your first filter.
Prerequisite
The Chat Filter addon requires a basic understanding of certain technical concepts such as regular expression search patterns which may make the use of this addon fairly intimidating for some.
Configuring the Chat Filter Addon
Open Preferences using the keyboard combination Command Comma, browse to the Addons section in the top-right corner of the navigation bar, and select Chat Filter from the menu that appears.
This will bring forward the configuration panel for the Chat Filter addon which can be used to create a new filter or modify those that already exist.
As seen below, the configuration panel has three key elements:
They are:
- This list contains filters that are already configured. Each filter can be double clicked to begin editing it.
- The add button (+) can be used to create a new filter and the remove button (-) can be used to remove a filter.
- In addition to double clicking a filter, a filter that is selected can be edited using the “Edit” button.
Creating Your First Filter
Click the add button (+) in the bottom left corner of the Chat Filter addon configuration panel to add your first filter.
Once clicked, a window will appear that is visually similar to the following:
The text field labeled Filter Title1 is the title for this filter and is referenced to in the configuration panel.
The Filter Match2 text field is used to configure the search pattern that will be used to determine whether this particular filter will successfully match the contents of a message. In most cases, entering something as simple as “Apple” is enough to create a filter that matches messages that contain the word “Apple”.
Advanced users that require fine-grained matching can enter an ICU-compatible regular expression search pattern.
The following list contains several advanced search pattern examples:
^Apple$will match the exact message “Apple”^!helpwill match any message starting with “!help”^([0-9]+)$will match any message that only contains numbersapple\.comwill match any message that contains “apple.com”
The Filter Action3 text field hosts a list of one ore more commands, each placed on a new line and prefixed with a forward slash, that will be automatically performed if the contents of an incoming message successfully matches the configured search pattern. A filter does not require a Filter Action. This text field can be left blank. A filter can do more than automatically perform a set of commands as described later in this tutorial.
If you chose to automatically perform a set of commands, then context can be provided to each command using one of the many “Filter Action Tokens” which can be dragged into the Filter Action text field
For this tutorial, the search pattern “Apple sucks, Google rocks!” is used to punish users that think that Google is better than Apple. When a message matches this search pattern the Filter Action is used to automatically give ourself operator status in the channel the message is posted within, ban the user, kick the user, then remove operator status.
See the image presented below for this tutorial's values:
Filter Scope
The “Filter Scope” tab can be clicked at the top of the window to define additional rules for the filter such as the channels that the filter restricted to or the type of content matched against.
See the image presented below for an example configuration:
- This group of radio buttons can be used to restrict the filter to only channels, only queries (private messages), or any possible combination of joined channels that you select.
- These three checkboxes can be individually toggled to restrict the type of content that the filter matches against.
- This list can be used to restrict the filter to specific channels when the “Specific Items” radio button is selected.
Filter Notes
Depending on its intended use case, a filter may have a very complex, difficult to understand search pattern which can make it difficult to edit at a later time if your memory has lapsed. If you click the “Filter Notes” tab when editing a filter, the Chat Filter addon offers a large text box to enter notes and examples into for your filter to help you remember the purpose of the filter and what its intended matches are.
Advanced Options
Several advanced options can be reached by clicking the “Advanced Options” tab when editing a filter.
The most notable of these options are the Sender Match2 option and the Forward to3 option.
The Sender Match2 option acts as an additional rule to determine whether the filter matches successfully. The value of this option is a regular expression search pattern which is compared against the hostmask (address, nickname, and username combined) of the message author. If a message is from a server, then the value this search pattern is compared against is the address of the server that sent the message.
An example search pattern is ^Josh! which
matches messages by the user with the nickname “Josh”
Another example is ^([^!@]+)$ which match only messages from a server.
The Forward to3 option can be used to send a copy of the message matched by a filter to a separate query window. The value of this option is the name of the query to send the message copy to.
A few examples are: “Operator Messages”, “Server Notices”, or “Messages by Josh”