Handler Objects#

WhatsApp.add_handlers(*handlers: Handler) → None#

Add handlers programmatically instead of using decorators.

Example

>>> from pywa.handlers import MessageHandler, CallbackButtonHandler
>>> from pywa import filters as fil
>>> print_message = lambda _, msg: print(msg)
>>> wa = WhatsApp(...)
>>> wa.add_handlers(
...     MessageHandler(print_message, fil.text),
...     CallbackButtonHandler(print_message),
... )

Parameters:: handlers – The handlers to add.

WhatsApp.add_flow_request_handler(handler: FlowRequestHandler) → FlowRequestCallbackWrapper#

Add a flow request handler.

Example

>>> from pywa.handlers import FlowRequestHandler
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> wa.add_flow_request_handler(
...     FlowRequestHandler(
...         endpoint="/flow",
...         callback=lambda _, flow: ...,
...     )
... ).set_errors_handler(lambda _, error: ...)
... .add_handler(lambda _, flow: ..., screen="RECOMMENDED")

Parameters:: handler – The flow request handler to add.
Returns:: A wrapper to help split the logic of the handler.

WhatsApp.remove_handlers(*handlers: Handler, silent: bool = False) → None#

Remove handlers programmatically (not flow handlers).

If you registered callback with decorator (so uou don’t have reference to the handler object), you can use the remove_callbacks() method to remove the callback.

Example

>>> from pywa.handlers import MessageHandler, CallbackButtonHandler
>>> from pywa import filters as fil
>>> print_message = lambda _, msg: print(msg)
>>> wa = WhatsApp(...)
>>> message_handler = MessageHandler(print_message, fil.text)
>>> wa.add_handlers(message_handler)
>>> wa.remove_handlers(message_handler)

Parameters:

handlers – The handlers to remove.
silent – Whether to suppress the error if the handler is not registered (default: False).

Raises:

ValueError – If the handler is not registered and silent is False.

class pywa.handlers.MessageHandler(callback: Callable[[WhatsApp, Message], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, Message], bool | Awaitable[bool]], priority: int = 0)#

Handler for incoming pywa.types.Message.

You can use the on_message() decorator to register a callback for this type.

Example

>>> from pywa import WhatsApp, filters as fil
>>> wa = WhatsApp(...)
>>> print_text_messages = lambda _, msg: print(msg)
>>> wa.add_handlers(MessageHandler(print_text_messages, fil.text))

Parameters:

callback – The callback function (Takes the pywa.WhatsApp instance and a pywa.types.Message as arguments)
*filters – The filters to apply to the callback (Takes a pywa.WhatsApp instance and a pywa.types.Message and returns a bool)
priority – The priority of the handler (default: 0)

class pywa.handlers.CallbackButtonHandler(callback: Callable[[WhatsApp, CallbackButton], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, CallbackButton], bool | Awaitable[bool]], factory: _CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False, priority: int = 0)#

Handler for callback buttons (User clicks on a pywa.types.Button).

You can use the on_callback_button() decorator to register a handler for this type.

Example

>>> from pywa import WhatsApp, filters as fil
>>> wa = WhatsApp(...)
>>> print_btn = lambda _, btn: print(btn)
>>> wa.add_handlers(CallbackButtonHandler(print_btn, fil.startswith('id:')))

Parameters:

callback – The callback function (gets the WhatsApp instance and the callback as arguments)
*filters – The filters to apply to the handler (Takes a pywa.WhatsApp instance and a pywa.types.CallbackButton and returns a bool)
factory – The constructor/s to use to construct 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).
priority – The priority of the handler (default: 0)

class pywa.handlers.CallbackSelectionHandler(callback: Callable[[WhatsApp, CallbackSelection], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, CallbackSelection], bool | Awaitable[bool]], factory: _CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False, priority: int = 0)#

Handler for callback selections (User selects an option from pywa.types.SectionList).

You can use the on_callback_selection() decorator to register a handler for this type.

Example

>>> from pywa import WhatsApp, filters as fil
>>> wa = WhatsApp(...)
>>> print_selection = lambda _, sel: print(sel)
>>> wa.add_handlers(CallbackSelectionHandler(print_selection, fil.startswith('id:')))

Parameters:

callback – The callback function. (Takes a pywa.WhatsApp instance and a pywa.types.CallbackSelection as arguments)
*filters – The filters to apply to the handler. (Takes a pywa.WhatsApp instance and a pywa.types.CallbackSelection and returns a bool)
factory – The constructor/s to use to construct 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)
priority – The priority of the handler (default: 0)

class pywa.handlers.FlowCompletionHandler(callback: Callable[[WhatsApp, FlowCompletion], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, FlowCompletion], bool | Awaitable[bool]], priority: int = 0)#

Handler for pywa.types.FlowCompletion updates (Flow is completed).

You can use the on_flow_completion() decorator to register a handler for this type.

Example

>>> from pywa import WhatsApp
>>> wa = WhatsApp(...)
>>> print_flow = lambda _, flow: print(flow)
>>> wa.add_handlers(FlowCompletionHandler(print_flow)

Parameters:

callback – The callback function (Takes a pywa.WhatsApp instance and a pywa.types.FlowCompletion as arguments)
*filters – The filters to apply to the handler (Takes a pywa.WhatsApp instance and a pywa.types.FlowCompletion and returns a bool)
priority – The priority of the handler (default: 0)

class pywa.handlers.FlowRequestHandler(callback: _FlowRequestHandlerT, *, 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)#

A handler for Flow Data Exchange requests.

Parameters:

callback – The function to call when a request is received (Takes a pywa.WhatsApp instance and a pywa.types.FlowRequest as arguments and returns a pywa.types.FlowResponse.
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)

class pywa.handlers.MessageStatusHandler(callback: Callable[[WhatsApp, MessageStatus], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, MessageStatus], bool | Awaitable[bool]], factory: _CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False, priority: int = 0)#

Handler for pywa.types.MessageStatus updates (Message is sent, delivered, read, failed, etc…).

You can use the on_message_status() decorator to register a handler for this type.

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

Example

>>> from pywa import WhatsApp, filters as fil
>>> wa = WhatsApp(...)
>>> print_failed_messages = lambda _, msg: print(msg)
>>> wa.add_handlers(MessageStatusHandler(print_failed_messages, fil.message_status.failed))

Parameters:

callback – The callback function (Takes a pywa.WhatsApp instance and a pywa.types.MessageStatus as arguments)
*filters – The filters to apply to the handler (Takes a pywa.WhatsApp instance and a pywa.types.MessageStatus and returns a bool)
factory – The constructor/s to use to construct 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)
priority – The priority of the handler (default: 0)

class pywa.handlers.ChatOpenedHandler(callback: Callable[[WhatsApp, ChatOpened], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, ChatOpened], bool | Awaitable[bool]], priority: int = 0)#

Handler for pywa.types.ChatOpened

You can use the on_chat_opened() decorator to register a handler for this type.

Example

>>> from pywa import WhatsApp
>>> wa = WhatsApp(...)
>>> print_chat_opened = lambda _, msg: print(msg)
>>> wa.add_handlers(ChatOpenedHandler(print_chat_opened))

Parameters:

callback – The callback function (Takes a pywa.WhatsApp instance and a pywa.types.ChatOpened as arguments)
*filters – The filters to apply to the handler (Takes a pywa.WhatsApp instance and a pywa.types.ChatOpened and returns a bool)
priority – The priority of the handler (default: 0)

class pywa.handlers.TemplateStatusHandler(callback: Callable[[WhatsApp, TemplateStatus], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, TemplateStatus], bool | Awaitable[bool]], priority: int = 0)#

Handler for pywa.types.TemplateStatus updates (Template message is approved, rejected etc…).

You can use the on_template_status() decorator to register a handler for this type.

Example

>>> from pywa import WhatsApp, filters as fil
>>> wa = WhatsApp(...)
>>> print_template_status = lambda _, msg: print(msg)
>>> wa.add_handlers(TemplateStatusHandler(
...     print_template_status,
...     fil.template_status.on_event(TemplateStatus.TemplateEvent.APPROVED)
... ))

Parameters:

callback – The callback function (Takes a pywa.WhatsApp instance and a pywa.types.TemplateStatus as arguments)
*filters – The filters to apply to the handler (Takes a pywa.WhatsApp instance and a pywa.types.TemplateStatus and returns a bool)
priority – The priority of the handler (default: 0)

class pywa.handlers.RawUpdateHandler(callback: Callable[[WhatsApp, dict], Any | Awaitable[Any]], *filters: Callable[[WhatsApp, dict], bool | Awaitable[bool]], priority: int = 0)#

A raw update callback.

This handler will be called for EVERY update received from WhatsApp, even if it’s not sent to the client phone number.
You can use the on_raw_update() decorator to register a handler for this type.

Example

>>> from pywa import WhatsApp
>>> wa = WhatsApp(...)
>>> print_updates = lambda _, data: print(data)
>>> wa.add_handlers(RawUpdateHandler(print_updates))

Parameters:

handler – The callback function (Takes a pywa.WhatsApp instance and a dict as arguments)
*filters – The filters to apply to the handler (Takes a pywa.WhatsApp instance and a dict and returns a bool)
priority – The priority of the handler (default: 0)

Handler Objects

Contents

Handler Objects#