🔬 Filters

🔬 Filters#

Filters are used by the handlers to determine if they should handle an update or not.

The library provides some built-in filters that you can use. The filters are located in the pywa.filters module.

Here is an example of how to use them:

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#

You can combine filters with logical operators:

  • &: and

  • |: or

  • ~: not

Here is some examples:

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

Keep in mind that all match-filters (matches(), contains(), etc) will return True if ANY of the given matches are found. so there is no need to do something like filters.matches('hello') | filters.matches('hi'), you can just do filters.matches('hello', 'hi').

Custom Filters#

You can create your own filters by providing a function that takes the client and the update and returns a boolean. If the function returns True, the handler will handle the update, otherwise it will be ignored.

Note

  • The custom filter function should be wrapped with pywa.filters.new() to be used as a filter.

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

  • You can use async functions as filters only if you using 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: 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: Message):
    msg.reply('You said something without xyz!')

Built-in Filters#