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: _MessageCallback, filters: Filter = None, 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
>>> wa = WhatsApp(...)
>>> print_text_messages = lambda _, msg: print(msg)
>>> wa.add_handlers(MessageHandler(print_text_messages, filters.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
priority – The priority of the handler (default: 0)

class pywa.handlers.CallbackButtonHandler(callback: _CallbackButtonCallback, filters: Filter = None, factory: type[CallbackData] | None = None, 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
>>> wa = WhatsApp(...)
>>> print_btn = lambda _, btn: print(btn)
>>> wa.add_handlers(CallbackButtonHandler(print_btn, filters.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 to use to construct the callback data.
priority – The priority of the handler (default: 0)

class pywa.handlers.CallbackSelectionHandler(callback: _CallbackSelectionCallback, filters: Filter = None, factory: type[CallbackData] | None = None, 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
>>> wa = WhatsApp(...)
>>> print_selection = lambda _, sel: print(sel)
>>> wa.add_handlers(CallbackSelectionHandler(print_selection, filters.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
factory – The constructor to use to construct the callback data.
priority – The priority of the handler (default: 0)

class pywa.handlers.FlowCompletionHandler(callback: _FlowCompletionCallback, filters: Filter = None, 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
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: _MessageStatusCallback, filters: Filter = None, factory: type[CallbackData] | None = None, 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, types, filters
>>> wa = WhatsApp(...)
>>> print_failed_messages = lambda _, msg: print(msg)
>>> wa.add_handlers(MessageStatusHandler(print_failed_messages, filters.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
factory – The constructor to use to construct the callback data.
priority – The priority of the handler (default: 0)

class pywa.handlers.ChatOpenedHandler(callback: _ChatOpenedCallback, filters: Filter = None, 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
priority – The priority of the handler (default: 0)

class pywa.handlers.TemplateStatusHandler(callback: _TemplateStatusCallback, filters: Filter = None, 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
>>> wa = WhatsApp(...)
>>> print_template_status = lambda _, msg: print(msg)
>>> wa.add_handlers(TemplateStatusHandler(print_template_status))

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
priority – The priority of the handler (default: 0)

class pywa.handlers.RawUpdateHandler(callback: _RawUpdateCallback, filters: Filter = None, 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:

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

Handler Objects

Contents

Handler Objects#