🔬 Filters

🔬 Filters#

Filters are used by handlers to decide whether an update should be handled or ignored.

The library provides several built-in filters, available in the pywa.filters module.

Basic Usage#

from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

@wa.on_message(filters.startswith("Hello", "Hi", ignore_case=True))
def handle_hello(wa: WhatsApp, msg: types.Message):
    msg.react("👋")
    msg.reply(
        f"Hello {msg.from_user.name}!",
        buttons=[types.Button("Click me!", "click")]
    )

@wa.on_callback(filters.matches("click"))
def handle_click(wa: WhatsApp, clb: types.CallbackButton):
    clb.reply("You clicked me!")

Combining Filters#

Filters can be combined with logical operators:

  • & → and

  • | → or

  • ~ → not

from pywa import filters

# image with caption
filters.image & filters.has_caption

# text or image
filters.text | filters.image

# message must not contain "bad word"
~filters.contains("bad word")

Tip

All match-filters (matches(), contains() etc.) return True if any of the given options match. So instead of writing:

filters.matches("hello") | filters.matches("hi")

You can simply write:

filters.matches("hello", "hi")

Custom Filters#

You can define your own filters by writing a function that takes the client and the update, and returns a boolean.

If the function returns True → the handler will process the update. If it returns False → the update will be ignored.

Note

  • Custom filters must be wrapped with pywa.filters.new().

  • You can combine custom and built-in filters using logical operators.

  • Async functions can be used as filters only with the async client.

from pywa import WhatsApp, types, filters

def without_xyz_filter(_: WhatsApp, msg: types.Message) -> bool:
    return msg.text and "xyz" not in msg.text

wa = WhatsApp(...)

@wa.on_message(filters.new(without_xyz_filter))
def messages_without_xyz(wa: WhatsApp, msg: types.Message):
    msg.reply("You said something without xyz!")

# Or with lambda:
@wa.on_message(filters.new(lambda _, msg: msg.text and "xyz" not in msg.text))
def messages_without_xyz(wa: WhatsApp, msg: types.Message):
    msg.reply("You said something without xyz!")

Built-in Filters#

Contents