Common filters

Common filters#

pywa.filters.new(func: Callable[[WhatsApp, _V], bool | Awaitable[bool]], name: str | None = None) → Filter[_V]#
pywa.filters.new(func: str | None = None, name: str | None = None) → Callable[[Callable[[WhatsApp, _V], bool | Awaitable[bool]]], Filter[_V]]

A factory function to create custom filter from a function (sync or async).

>>> from pywa import WhatsApp, filters, types

>>> wa = WhatsApp(...)

>>> @filters.new
... def is_registered(_: WhatsApp, msg: types.Message) -> bool:
...     return my_db.is_user_registered(msg.from_user.bsuid)

Using it:

>>> @wa.on_message(is_registered)
... def only_registered_users(wa: WhatsApp, msg: types.Message):
...     msg.reply("Hello registered user!")

Or passing the function directly:

>>> @wa.on_message(filters.new(lambda _, msg: my_db.is_user_registered(msg.from_user.bsuid)))
... def only_registered_users(wa: WhatsApp, msg: types.Message):
...     msg.reply("Hello registered user!")
Return type:

Filter[Any] | Callable[[Callable[[WhatsApp, Any], bool | Awaitable[bool]]], Filter[Any]]

filters.message: Filter[Message] = <pywa.filters.message object>#
filters.callback_button: Filter[CallbackButton] = <pywa.filters.callback_button object>#
filters.callback_selection: Filter[CallbackSelection] = <pywa.filters.callback_selection object>#
filters.message_status: Filter[MessageStatus] = <pywa.filters.message_status object>#
filters.flow_completion: Filter[FlowCompletion] = <pywa.filters.flow_completion object>#
filters.call_connect: Filter[CallConnect] = <pywa.filters.call_connect object>#
filters.call_terminate: Filter[CallTerminate] = <pywa.filters.call_terminate object>#
filters.call_status: Filter[CallStatus] = <pywa.filters.call_status object>#
filters.call_permission_update: Filter[CallPermissionUpdate] = <pywa.filters.call_permission_update object>#
filters.user_marketing_preferences: Filter[UserMarketingPreferences] = <pywa.filters.user_marketing_preferences object>#
filters.template_status: Filter[TemplateStatusUpdate] = <pywa.filters.template_status object>#
filters.template_category: Filter[TemplateCategoryUpdate] = <pywa.filters.template_category object>#
filters.template_quality: Filter[TemplateQualityUpdate] = <pywa.filters.template_quality object>#
filters.template_components: Filter[TemplateComponentsUpdate] = <pywa.filters.template_components object>#
filters.phone_number_change: Filter[PhoneNumberChange] = <pywa.filters.phone_number_change object>#
filters.identity_change: Filter[IdentityChange] = <pywa.filters.identity_change object>#
filters.account_update: Filter[AccountUpdate] = <pywa.filters.account_update object>#
filters.private: Filter[Message] = <pywa.filters.private object>#
filters.group: Filter[Message] = <pywa.filters.group object>#
pywa.filters.sent_to(*, display_phone_number=None, phone_number_id=None)#

Filter for updates that are sent to the given phone number.

  • Use this filter when you choose not filter updates (e.g. WhatsApp(..., filter_updates=False)) so you can still filter for messages that are sent to specific phone numbers.

>>> sent_to(display_phone_number="+1 555-555-5555")
>>> sent_to(phone_number_id="123456789")
Return type:

Filter[BaseUserUpdate]

pywa.filters.update_id(id_)#

Filter for updates that have the given id.

>>> update_id("wamid.HBKHUIyNTM4NjAfiefhwojfMTNFQ0Q2MERGRjVDMUHUIGGA=")
Return type:

Filter[BaseUpdate]

pywa.filters.waba_id(id_)#

Filter for updates that their WABA ID matches the given id.

>>> waba_id("105102735943269")
Return type:

Filter[BaseUpdate]

filters.sent_to_me: Filter[BaseUserUpdate] = <pywa.filters.sent_to_me object>#
pywa.filters.from_users(*ids)#

Filter for updates that are sent from the given IDs (BSUID, PARENT_BSUID, WA_ID, or PHONE_NUMBER).

>>> from_users("US.13491208655302741918", "+1 (631) 555-1234", "16315551234")
Return type:

Filter[BaseUserUpdate]

pywa.filters.without_wa_id()#

Filter for updates that their sender doesn’t have a wa_id (when the user enables username)

pywa.filters.from_countries(*prefixes_or_codes)#

Filter for updates that are sent from the given country codes.

  • You can pass either country codes (e.g. “US”, “IL”) or phone number prefixes (e.g. “+1”, “972”).

  • See https://countrycode.org/ for a list of country codes.

>>> from_countries("972", "1", "+972", "US", "IL") # Israel and USA
Return type:

Filter[BaseUserUpdate]

pywa.filters.matches(*strings, ignore_case=False)#

Filter for messages that are matching (==) any of the given strings.

The strings will be checked against the following fields:

  • Message: text, caption

  • CallbackButton: data

  • CallbackSelection: data

  • MessageStatus: tracker

  • FlowCompletion: token, body

>>> matches("Hello", "Hi")
Parameters:

  • *strings (str) – The strings to match.

  • ignore_case (bool) – Whether to ignore case when matching.

Return type:

Filter[Any]

pywa.filters.contains(*words, ignore_case=False)#

Filter for updates that contain any of the given words.

The words will be checked against the following fields:

  • Message: text, caption

  • CallbackButton: data

  • CallbackSelection: data

  • MessageStatus: tracker

  • FlowCompletion: token, body

>>> contains("Hello", "Hi", ignore_case=True)
Parameters:

  • *words (str) – The words to match.

  • ignore_case (bool) – Whether to ignore case when matching.

Return type:

Filter[Any]

pywa.filters.startswith(*prefixes, ignore_case=False)#

Filter for updates that start with any of the given prefixes.

The prefixes will be checked against the following fields:

  • Message: text, caption

  • CallbackButton: data

  • CallbackSelection: data

  • MessageStatus: tracker

  • FlowCompletion: token, body

>>> startswith("Hello", "Hi", ignore_case=True)
Parameters:

  • *prefixes (str) – The prefixes to match.

  • ignore_case (bool) – Whether to ignore case when matching.

Return type:

Filter[Any]

pywa.filters.endswith(*suffixes, ignore_case=False)#

Filter for updates that end with any of the given suffixes.

The suffixes will be checked against the following fields:

  • Message: text, caption

  • CallbackButton: data

  • CallbackSelection: data

  • MessageStatus: tracker

  • FlowCompletion: token, body

>>> endswith("Hello", "Hi", ignore_case=True)
Parameters:

  • *suffixes (str) – The suffixes to match.

  • ignore_case (bool) – Whether to ignore case when matching.

Return type:

Filter[Any]

pywa.filters.regex(*patterns, flags=0)#

Filter for updates that match any of the given regex patterns.

The patterns will be checked against the following fields:

  • Message: text, caption

  • CallbackButton: data

  • CallbackSelection: data

  • MessageStatus: tracker

  • FlowCompletion: token, body

>>> regex(r"Hello|Hi")
Parameters:

  • *patterns (str | Pattern) – The regex patterns to match.

  • flags (int) – The regex flags to use.

Return type:

Filter[Any]