Ctrl+K

Handler Decorators

Handler Decorators#

WhatsApp.on_message(*filters: Callable[[WhatsApp, Message], bool]) → Callable[[Callable[[WhatsApp, Message], Any]], Callable[[WhatsApp, Message], Any]]#

Decorator to register a function as a handler for incoming pywa.types.Message (User sends a message).

Example

>>> from pywa.types import Button
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_message(fil.text.matches("Hello", "Hi", ignore_case=True))
... def hello_handler(_: WhatsApp, msg: Message):
...     msg.react("👋")
...     msg.reply_text(text="Hello from PyWa!", quote=True, buttons=[Button("Help", data="help")
Parameters:

*filters – Filters to apply to the incoming messages (filters are function that take a pywa.WhatsApp instance and the incoming pywa.types.Message and return a boolean).

WhatsApp.on_callback_button(*filters: Callable[[WhatsApp, CallbackButton], bool], factory: CallbackDataT = <class 'str'>) → Callable[[Callable[[WhatsApp, CallbackButton], Any]], Callable[[WhatsApp, CallbackButton], Any]]#

Decorator to register a function as a handler when a user clicks on a pywa.types.Button.

IMPORTANT: If factory provided, The filters have no access to the constructed callback data, only the raw string (When subclassing pywa.types.CallbackData as the factory, a matching filter is automatically added, so there is no need to add it manually).

Example

>>> from pywa.types import CallbackButton
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_callback_button(fil.callback.data_matches("help"))
... def help_handler(_: WhatsApp, btn: CallbackButton):
...     btn.reply_text(text="What can I help you with?")
Parameters:

  • *filters – Filters to apply to the incoming callback button presses (filters are function that take a pywa.WhatsApp instance and the incoming pywa.types.CallbackButton and return bool).

  • factory – The constructor/s to use for the callback data (default: str).

WhatsApp.on_callback_selection(*filters: Callable[[WhatsApp, CallbackSelection], bool], factory: CallbackDataT = <class 'str'>) → Callable[[Callable[[WhatsApp, CallbackSelection], Any]], Callable[[WhatsApp, CallbackSelection], Any]]#

Decorator to register a function as a handler when a user selects an option from a pywa.types.SectionList.

IMPORTANT: If factory provided, The filters have no access to the constructed callback data, only the raw string (When subclassing pywa.types.CallbackData as the factory, a matching filter is automatically added, so there is no need to add it manually).

Example

>>> from pywa.types import CallbackSelection
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_callback_selection(fil.callback.data_startswith("id:"))
... def id_handler(_: WhatsApp, sel: CallbackSelection):
...     sel.reply_text(text=f"Your ID is {sel.data.split(':', 1)[1]}")
Parameters:

  • *filters – Filters to apply to the incoming callback selections (filters are function that take a pywa.WhatsApp instance and the incoming pywa.types.CallbackSelection and return bool).

  • factory – The constructor/s to use for the callback data (default: str).

WhatsApp.on_message_status(*filters: Callable[[WhatsApp, MessageStatus], bool]) → Callable[[Callable[[WhatsApp, MessageStatus], Any]], Callable[[WhatsApp, MessageStatus], Any]]#

Decorator to register a function as a handler for incoming message status changes (Message is sent, delivered, read, failed, etc…).

DO NOT USE THIS HANDLER WITHOUT FILTERS TO SEND MESSAGES, IT WILL CAUSE AN INFINITE LOOP!

Example

>>> from pywa.types import MessageStatus
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_message_status(fil.message_status.failed)
... def delivered_handler(client: WhatsApp, status: MessageStatus):
...     print(f"Message {status.id} failed to send to {status.from_user.wa_id}: {status.error.message})

Args: *filters: Filters to apply to the incoming message status changes (filters are function that take a

pywa.WhatsApp instance and the incoming pywa.types.MessageStatus and return bool).

WhatsApp.on_template_status(*filters: Callable[[WhatsApp, TemplateStatus], bool]) → Callable[[Callable[[WhatsApp, TemplateStatus], Any]], Callable[[WhatsApp, TemplateStatus], Any]]#

Decorator to register a function as a handler for pywa.types.TemplateStatus updates (Template message is approved, rejected etc…).

Example

>>> from pywa.types import TemplateStatus
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_template_status(fil.template_status.on_event(TemplateStatus.TemplateEvent.APPROVED))
... def approved_handler(client: WhatsApp, status: TemplateStatus):
...     print(f"Template {status.message_template_name} just got approved!")
Parameters:

*filters – Filters to apply to the incoming template status changes (filters are function that take a pywa.WhatsApp instance and the incoming pywa.types.TemplateStatus and return bool).

WhatsApp.on_raw_update(*filters: Callable[[WhatsApp, dict], bool]) → Callable[[Callable[[WhatsApp, dict], Any]], Callable[[WhatsApp, dict], Any]]#

Decorator to register a function as a handler for raw updates (dict).

  • This handler is called for EVERY update received from WhatsApp, even if it’s not sent to the client phone number.

  • Shortcut for add_handlers() with a RawUpdateHandler.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_raw_update()
... def raw_update_handler(_: WhatsApp, update: dict):
...     print(update)
Parameters:

*filters – Filters to apply to the incoming updates (filters are function that take a pywa.WhatsApp instance and the incoming update dict and return a bool if the update should be handled).

Contents