Filters

Filters are a powerful tool to create your own custom, filtered channel splits. Filters allow you to selectively show messages that satisfy your own custom criteria: show subscribers' messages, moderator messages, channel point redemptions, new subscriptions, and more.

Looking for inspiration? Look at some example filters.

Introduction to Filters

Filters can be applied to splits to provide a selective view of messages. Filters are created in the Settings page and are applied by opening the Split menu (three dots) and selecting "Set filters". Applied filters are saved when you close and open Chatterino.

Multiple filters can be applied to a Split. A message must pass all applied filters for it to be displayed.

Simple filters are available through the Channel Filter Creator dialog. Advanced filters take inspiration from many programming languages, and the full description of keywords and operators can be found below.

Writing your own filters

To begin writing your own filters, take a look at the available operators and variables below.

For most tasks involving the message content, you can make use of the contains operator, or the matches operator with a regular expression.
Then, try to break your desired behavior into multiple conditions. Combine them like this:

• If you need all the conditions satisfied, combine them with AND (condition1 && condition2)
• If you only need one of the conditions, combine them with OR (condition1 || condition2)
• If you need the opposite of one of the conditions, wrap it with parentheses and add a NOT: !(condition)

Example

Consider the following intention: "Only show me messages that are from moderators and mention me". We can break this filter into two individual conditions:

1. Messages that are from moderators
2. Messages that mention me

We can then write the corresponding filter parts:

1. author.badges contains "moderator"
2. message.content contains "@my_name"

Finally, because we want both of these conditions to be true, we combine them with the AND operator && and end up with this final filter:

(author.badges contains "moderator") && (message.content contains "@my_name")

Quick Add

If you already have a filter, you can use the Quick Add button and paste your filter into the Filter section.

Terminology

Here is some terminology that you'll encounter in the rest of this document.

1. Value: A value is the simplest element of a filter. It can take on multiple forms: a number, a string (i.e. text), a regular expression, or a list of multiple values.
2. Type: A type describes the general form of a value. For example, every number has type Int. Every string has type String.
3. Variable: A variable is a placeholder for some information about a message. For example, the variable message.content represents the text of a message
4. Operator: An operator acts on one or two values and evaluates to another value. For example, the plus operator + can add two numbers, 1 + 1 or concatenate strings, "a" + "b"

Example filters

• message.content contains "hello"
  • Only messages that contain the phrase hello
• message.length < 40 || author.subbed
  • Messages that are less than 40 characters long, OR are sent by a subscriber.
• channel.name == "somestreamer" && author.badges contains "moderator"
  • Messages that originated in the channel somestreamer AND are from users with a moderator badge

Filter Syntax + Semantics

This section is aimed at technical users who have experience with general purpose programming languages.

A filter must be a valid expression. An expression is comprised of conditions and values which are evaluated to a single True or False value to decide whether to filter a message. Evaluating to something other than True or False will lead to all messages being filtered out.

Values

A value can be:

1. An integer (123, 5)
2. A string ("hello", "this is a string")
3. A variable (author.name, message.length)
   • Technically, a variable isn't a value, but is given value by substitution
   • When a filter is evaluated, variables are replaced with the values they represent
4. A regular expression (r"\d\d\d\d")
5. A list of values ({123, "hello", author.name})

Regular expressions are similar to strings, but are denoted with an r before the opening quotation mark (e.g. r"something"). To make a regular expression case-insensitive, use ri before the opening quotation mark (e.g. ri"something").

Literals:

Name	Example
Int	123, 5
String	"Hello there", "Escaped \" quote"
RegEx	r"\d\d\d\d", ri"something.*"
List	`{"list item", 123}

Operators

Binary operators act on two values:

• 1 + 2
• author.subbed && flags.highlighted
• "long sentence" contains "ten"

Unary operators act on one value:

• !author.subbed

The following operators are available:

Operator	Description
&&	Logical AND
||	Logical OR
!	Negation
==	Equals
!=	Not equals
<	Less than
<=	Less than or equal to
>	Greater than
>=	Greater than or equal to
contains	String, List, or Map contains
startswith	String or List starts with text or value, respectively
endswith	String or List ends with text or value, respectively
match	Match string with regular expression
+	Add (or string concatenation)
-	Subtract
*	Multiply
/	Divide (integer)
%	Modulus

Please read about the type rules to better understand the evaluation semantics for operators that take multiple data types.

Variables

The following variables are available:

Variable	Type	Description
Author		User who sent the message
author.badges	List	List of author's badges
author.color	Color*	Color code of author, or none
author.name	String	Display name of author
author.no_color	Bool	Whether the author has no color set (i.e. gray name)
author.subbed	Bool	Whether author is subscribed
author.sub_length	Int	How long author has been subscribed (or zero)
Channel		The channel where the message was sent
channel.name	String	Channel name
channel.watching	Bool	Whether the channel is being watched (requires Chatterino extension)
channel.live	Bool	Whether the channel is currently live
Flags		Message-specific flags
flags.highlighted	Bool	Whether the message is highlighted
flags.points_redeemed	Bool	Whether the message was redeemed through channel points
flags.sub_message	Bool	Whether the message is a sub/resub/gift message
flags.system_message	Bool	Whether the message is a system message (i.e. timeout/ban/info)
flags.reward_message	Bool	Whether the message is a redeemed channel point reward message
flags.first_message	Bool	Whether the message is the author's first message in the channel
flags.hype_chat	Bool	Whether the message is a message the author paid to keep in browser chat for an increased duration1
flags.cheer_message	Bool	Whether the message includes bits
flags.whisper	Bool	Whether the message is a whisper
flags.reply	Bool	Whether the message is a reply
flags.automod	Bool	Whether the message has automod information or actions
Message		Actual message sent
message.content	String	Message content
message.length	Int	Message length

*Note: To compare a Color, compare it to a color hex code string: author.color == "#FF0000"

Data types

The Chatterino filter language is typed, meaning that every value has a type and only specific combinations of types are allowed when using operators. Generally, you won't run in to issues. The type system exists to warn you about any mistakes that your filter contains.

Type Rules

Operator	Form	Result	Description
+	Int + Int	Int	Adds two integers
+	String + Any	String	Concatenates the first string with the second argument
-	Int - Int	Int	Subtracts two integers
*	Int * Int	Int	Multiplies two integers
/	Int / Int	Int	Divides two integers, discarding the remainder
%	Int % Int	Int	Computes the modulus of two integers
&&	Bool && Bool	Bool	Logical AND of two booleans
||	Bool || Bool	Bool	Logical OR of two booleans
==	Any == Any	Bool	Equality comparison of any two values
!=	Any != Any	Bool	Inequality comparison of any two values
>	Int > Int	Bool	Greater than comparison of two integers
>=	Int >= Int	Bool	Greater than or equal to comparison of two integers
<	Int < Int	Bool	Less than comparison of two integers
<=	Int <= Int	Bool	Less than or equal to comparison of two integers
startswith	List startswith Any	Bool	Checks whether the list has the given value as its first value
startswith	String startswith String	Bool	Checks whether the first string starts with the second string
endswith	List endswith Any	Bool	Checks whether the list has the given value as its last value
endswith	String endswith String	Bool	Checks whether the first string ends with the second string
contains	List contains Any	Bool	Checks whether the list contains the given value
contains	Map contains Any	Bool	Checks whether the map has the given value as a key
contains	String contains String	Bool	Checks whether the first string contains the second string
match	String match RegEx	Bool	Checks whether the string matches the given regular expression
match	String match {RegEx, n : Int}	String	Returns the nth matching capture group, or the empty string

Regular Expressions

Chatterino can match string variables to a regular expression, returning whether the expression matched or, optionally, the value of a capture group.

Simple matching

"some string" match r"some regex" returns True or False.

For example: message.content match r"\d\d"

Group capturing

"some string" match {r"some regex", capture number} returns False if no match or the value of the nth captured group.

For example: message.content match {r"(\d\d)/(\d\d)/(\d\d\d\d)", 3} matches the year component of a date like 12/31/2020.

(message.content match {r"(\d\d)/(\d\d)/(\d\d\d\d)", 3}) == "2020" will filter only messages that contain a written date with 2020 as the year.

Order of Operations

The order of operations in filters may not be exactly what you expect.

• Expressions in parentheses are evaluated first
• Math operations are evaluated from left to right, not by MDAS. 2 + 3 * 4 yields 20, not 14.
• a && b || c && d is evaluated as (a && b) || (c && d)
• a || b && c || d is evaluated as a || (b && c) || d

Basically, if you're unsure about the order of operations, use extra parentheses.

---

1. Replaced flags.elevated_message in 2.4.5 ↩

---

Last update: September 25, 2023 10:37:08