Using Filters¶

So far we’ve seen how to register a callback function that executes every time an update comes from the server, but there’s much more than that to come.

Here we’ll discuss about filters. Filters enable a fine-grain control over what kind of updates are allowed or not to be passed in your callback functions, based on their inner details.

Contents

Single Filters
Combining Filters
Advanced Filters

Single Filters¶

Let’s start right away with a simple example:

This example will show you how to only handle messages containing an Audio object and ignore any other message. Filters are passed as the first argument of the decorator:
```
from pyrogram import filters


@app.on_message(filters.audio)
def my_handler(client, message):
    print(message)
```

or, without decorators. Here filters are passed as the second argument of the handler constructor; the first is the callback function itself:

from pyrogram import filters
from pyrogram.handlers import MessageHandler

def my_handler(client, message):
    print(message)

app.add_handler(MessageHandler(my_handler, filters.audio))

Combining Filters¶

Filters can also be used in a more advanced way by inverting and combining more filters together using bitwise operators ~, & and |:

Use ~ to invert a filter (behaves like the not operator).
Use & and | to merge two filters (behave like and, or operators respectively).

Here are some examples:

Message is a text message and is not edited.

@app.on_message(filters.text & ~filters.edited)
def my_handler(client, message):
    print(message)

Message is a sticker and is coming from a channel or a private chat.

@app.on_message(filters.sticker & (filters.channel | filters.private))
def my_handler(client, message):
    print(message)

Advanced Filters¶

Some filters, like command() or regex() can also accept arguments:

Message is either a /start or /help command.

@app.on_message(filters.command(["start", "help"]))
def my_handler(client, message):
    print(message)

Message is a text message or a media caption matching the given regex pattern.

@app.on_message(filters.regex("pyrogram"))
def my_handler(client, message):
    print(message)

More handlers using different filters can also live together.

@app.on_message(filters.command("start"))
def start_command(client, message):
    print("This is the /start command")


@app.on_message(filters.command("help"))
def help_command(client, message):
    print("This is the /help command")


@app.on_message(filters.chat("PyrogramChat"))
def from_pyrogramchat(client, message):
    print("New message in @PyrogramChat")