For a finer grained control over what kind of messages will be allowed or not in your callback functions, you can use
This section makes use of Handlers to handle updates. Learn more at Update Handling.
This example will show you how to only handle messages containing an
Audioobject and ignore any other message:
from pyrogram import Filters @app.on_message(Filters.audio) def my_handler(client, message): print(message)
or, without decorators:
from pyrogram import Filters, MessageHandler def my_handler(client, message): print(message) app.add_handler(MessageHandler(my_handler, Filters.audio))
Filters can also be used in a more advanced way by inverting and combining more filters together using bitwise operators:
~to invert a filter (behaves like the
|to merge two filters (behave like
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)
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 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")
If you register handlers with overlapping filters, only the first one is executed and any other handler will be ignored.
In order to process the same message more than once, you can register your handler in a different group. Groups are identified by a number (number 0 being the default) and are sorted. This means that a lower group number has a higher priority.
For example, in:
@app.on_message(Filters.text | Filters.sticker) def text_or_sticker(client, message): print("Text or Sticker") @app.on_message(Filters.text) def just_text(client, message): print("Just Text")
just_text is never executed because
text_or_sticker already handles texts. To enable it, simply register the
function using a different group:
@app.on_message(Filters.text, group=1) def just_text(client, message): print("Just Text")
or, if you want
just_text to be fired before
-1, which is less than
@app.on_message(Filters.text, group=-1) def just_text(client, message): print("Just Text")
Pyrogram already provides lots of built-in
Filters to work with, but in case you can’t find
a specific one for your needs or want to build a custom filter by yourself (to be used in a different handler, for
example) you can use
At the moment, the built-in filters are intended to be used with the
An example to demonstrate how custom filters work is to show how to create and use one for the
CallbackQueryHandler. Note that callback queries updates are only received by Bots;
create and authorize your bot, then send a message with an inline keyboard to
yourself. This allows you to test your filter by pressing the inline button:
from pyrogram import InlineKeyboardMarkup, InlineKeyboardButton app.send_message( "username", # Change this to your username or id "Pyrogram's custom filter test", reply_markup=InlineKeyboardMarkup( [[InlineKeyboardButton("Press me", "pyrogram")]] ) )
For this basic filter we will be using only the first two parameters of
The code below creates a simple filter for hardcoded callback data. This filter will only allow callback queries containing “pyrogram” as data:
hardcoded_data = Filters.create( name="HardcodedData", func=lambda filter, callback_query: callback_query.data == "pyrogram" )
lambda operator in python is used to create small anonymous functions and is perfect for this example, the same
could be achieved with a normal function, but we don’t really need it as it makes sense only inside the filter itself:
def func(filter, callback_query): return callback_query.data == "pyrogram" hardcoded_data = Filters.create( name="HardcodedData", func=func )
The filter usage remains the same:
@app.on_callback_query(hardcoded_data) def pyrogram_data(client, callback_query): client.answer_callback_query(callback_query.id, "it works!")
Filters with Arguments¶
A much cooler filter would be one that accepts “pyrogram” or any other data as argument at usage time.
A dynamic filter like this will make use of the third parameter of
This is how a dynamic custom filter looks like:
def dynamic_data(data): return Filters.create( name="DynamicData", func=lambda filter, callback_query: filter.data == callback_query.data, data=data # "data" kwarg is accessed with "filter.data" )
And its usage:
@app.on_callback_query(dynamic_data("pyrogram")) def pyrogram_data(client, callback_query): client.answer_callback_query(callback_query.id, "it works!")