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 callback for incoming pywa.types.Message (User sends a message).

• Shortcut for add_handlers() with a MessageHandler.

Example

>>> from pywa.types import Button
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_message(fil.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: CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False) → Callable[[Callable[[WhatsApp, CallbackButton], Any]], Callable[[WhatsApp, CallbackButton], Any]]

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

• Shortcut for add_handlers() with a CallbackButtonHandler.

Example

>>> from pywa.types import CallbackButton
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_callback_button(fil.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. If the factory is a subclass of CallbackData, a matching filter is automatically added).

• factory_before_filters – Whether to apply the factory before the filters (default: False. If True, the filters will get the callback data after the factory is applied).

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

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

• Shortcut for add_handlers() with a CallbackSelectionHandler.

Example

>>> from pywa.types import CallbackSelection
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_callback_selection(fil.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. If the factory is a subclass of CallbackData, a matching filter is automatically added).

• factory_before_filters – Whether to apply the factory before the filters (default: False. If True, the filters will get the callback data after the factory is applied).

WhatsApp.on_flow_completion(*filters: Callable[[WhatsApp, FlowCompletion], bool]) → Callable[[Callable[[WhatsApp, FlowCompletion], Any]], Callable[[WhatsApp, FlowCompletion], Any]]

Decorator to register a function as a callback for pywa.types.FlowCompletion updates (Flow is completed).

• Shortcut for add_handlers() with a FlowCompletionHandler.

Example

>>> from pywa.types import FlowCompletion
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_flow_completion()
... def flow_handler(client: WhatsApp, flow: FlowCompletion):
...     print(f"Flow {flow.token} just got completed!. Flow data: {flow.response}")

Parameters:

*filters – Filters to apply to the incoming flow completion (filters are function that take a pywa.WhatsApp instance and the incoming pywa.types.FlowCompletion and return bool).

WhatsApp.on_flow_request(endpoint: str, *, acknowledge_errors: bool = True, handle_health_check: bool = True, private_key: str | None = None, private_key_password: str | None = None, request_decryptor: utils.FlowRequestDecryptor | None = None, response_encryptor: utils.FlowResponseEncryptor | None = None) → Callable[[Callable[[WhatsApp, FlowRequest], FlowResponse | FlowResponseError | dict | None]], Callable[[WhatsApp, FlowRequest], FlowResponse | FlowResponseError | dict | None]]

Decorator to register a function to handle and respond to incoming Flow Data Exchange requests.

Example

>>> from pywa import WhatsApp
>>> wa = WhatsApp(business_private_key='...', ...)
>>> @wa.on_flow_request('/feedback_flow')
... def feedback_flow_handler(_: WhatsApp, flow: FlowRequest) -> FlowResponse:
...     return FlowResponse(
...         version=flow.version,
...         screen="SURVEY",
...         data={
...             "default_text": "Please rate your experience with our service",
...             "text_required": True
...         }
...     )

Parameters:

• endpoint – The endpoint to listen to (The endpoint uri you set to the flow. e.g /feedback_flow).

• acknowledge_errors – Whether to acknowledge errors (The return value of the callback will be ignored, and pywa will acknowledge the error automatically).

• handle_health_check – Whether to handle health checks (The callback will not be called for health checks).

• private_key – The private key to use to decrypt the requests (Override the global business_private_key).

• private_key_password – The password to use to decrypt the private key (Override the global business_private_key_password).

• request_decryptor – The function to use to decrypt the requests (Override the global flows_request_decryptor)

• response_encryptor – The function to use to encrypt the responses (Override the global flows_response_encryptor)

WhatsApp.on_message_status(*filters: Callable[[WhatsApp, MessageStatus], bool], factory: CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False) → Callable[[Callable[[WhatsApp, MessageStatus], Any]], Callable[[WhatsApp, MessageStatus], Any]]

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

• Shortcut for add_handlers() with a MessageStatusHandler.

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})

Parameters:

• *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).

• factory – The constructor/s to use for the tracker data (default: str. If the factory is a subclass of CallbackData, a matching filter is automatically added).

• factory_before_filters – Whether to apply the factory before the filters (default: False. If True, the filters will get the tracker data after the factory is applied).

WhatsApp.on_chat_opened(*filters: Callable[[WhatsApp, ChatOpened], bool]) → Callable[[Callable[[WhatsApp, ChatOpened], Any]], Callable[[WhatsApp, ChatOpened], Any]]

Decorator to register a function as a callback for incoming chat opened (User opens a chat).

• Shortcut for add_handlers() with a ChatOpenedHandler.

Example

>>> from pywa.types import ChatOpened
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_chat_opened()
... def chat_opened_handler(client: WhatsApp, chat_opened: ChatOpened):
...     print(f"The user {chat_opened.from_user.wa_id} just opened a chat with us!")

Parameters:

*filters – Filters to apply to the incoming chat opened (filters are function that take a pywa.WhatsApp instance and the incoming pywa.types.ChatOpened 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 callback for pywa.types.TemplateStatus updates (Template message is approved, rejected etc…).

• Shortcut for add_handlers() with a TemplateStatusHandler.

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 callback for raw updates (dict).

• This callback 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 as dict and return a bool if the update should be handled).