Handler Objects

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: ...,
...     )
... ).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 Message updates (Text, media, etc…).

You can use the on_message() decorator to register a handler 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 WhatsApp client instance and a Message as positional 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 CallbackButton updates (user clicks on a Button or QuickReplyButton).

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. (Takes a WhatsApp instance and a CallbackButton as positional arguments)
filters – The filters to apply to the handler
factory – The CallbackData 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 CallbackSelection updates (user selects an SectionRow from a 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 WhatsApp instance and a CallbackSelection as positional arguments)
filters – The filters to apply to the handler
factory – The CallbackData 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 FlowCompletion updates (Flow completion updates).

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

Example

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

Parameters:

callback – The callback function (Takes a WhatsApp instance and a FlowCompletion as positional 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, 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).
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 MessageStatus updates (Message status updates, e.g. sent, delivered, read).

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 WhatsApp instance and a MessageStatus as positional arguments).
filters – The filters to apply to the handler
factory – The CallbackData constructor to use to construct the tracker data.
priority – The priority of the handler (default: 0)

class pywa.handlers.ChatOpenedHandler(callback: _ChatOpenedCallback, filters: Filter = None, priority: int = 0)#

Handler for ChatOpened updates (Chat is opened).

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 WhatsApp instance and a ChatOpened as positional arguments)
filters – The filters to apply to the handler
priority – The priority of the handler (default: 0)

class pywa.handlers.PhoneNumberChangeHandler(callback: _PhoneNumberChangeCallback, filters: Filter = None, priority: int = 0)#

Handler for PhoneNumberChange updates (user changes their phone number).

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

Example

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

Parameters:

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

class pywa.handlers.IdentityChangeHandler(callback: _IdentityChangeCallback, filters: Filter = None, priority: int = 0)#

Handler for IdentityChange updates (user changes their identity).

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

Example

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

Parameters:

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

class pywa.handlers.CallConnectHandler(callback: _CallConnectCallback, filters: Filter = None, priority: int = 0)#

Handler for CallConnect updates (Call connect updates).

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

Example

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

Parameters:

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

class pywa.handlers.CallTerminateHandler(callback: _CallTerminateCallback, filters: Filter = None, priority: int = 0)#

Handler for CallTerminate updates (Call terminate updates).

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

Example

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

Parameters:

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

class pywa.handlers.CallStatusHandler(callback: _CallStatusCallback, filters: Filter = None, factory: type[CallbackData] | None = None, priority: int = 0)#

Handler for CallStatus updates (Call status updates, e.g. ringing, accepted, rejected, etc.).

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

Example

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

Parameters:

callback – The callback function (Takes a WhatsApp instance and a CallStatus as positional arguments)
filters – The filters to apply to the handler
factory – The CallbackData constructor to use to construct the tracker data.
priority – The priority of the handler (default: 0)

class pywa.handlers.CallPermissionUpdateHandler(callback: _CallPermissionUpdateCallback, filters: Filter = None, priority: int = 0)#

Handler for CallPermissionUpdate updates (Call permission updates, e.g. when a user grants or revokes permission to receive calls).

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

Example

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

Parameters:

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

class pywa.handlers.UserMarketingPreferencesHandler(callback: _UserMarketingPreferencesCallback, filters: Filter = None, priority: int = 0)#

Handler for UserMarketingPreferences updates (User marketing preferences updates).

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

Example

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

Parameters:

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

class pywa.handlers.TemplateStatusUpdateHandler(callback: _TemplateStatusUpdateCallback, filters: Filter = None, priority: int = 0)#

Handler for TemplateStatusUpdate updates (Template status updates, e.g. approved, rejected etc.).

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

Example

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

Parameters:

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

class pywa.handlers.TemplateCategoryUpdateHandler(callback: _TemplateCategoryUpdateCallback, filters: Filter = None, priority: int = 0)#

Handler for TemplateCategoryUpdate updates (Template category updates, e.g. from UTILITY to MARKETING).

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

Example

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

Parameters:

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

class pywa.handlers.TemplateQualityUpdateHandler(callback: _TemplateQualityUpdateCallback, filters: Filter = None, priority: int = 0)#

Handler for TemplateQualityUpdate updates (Template quality updates, e.g. GREEN to RED).

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

Example

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

Parameters:

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

class pywa.handlers.TemplateComponentsUpdateHandler(callback: _TemplateComponentsUpdateCallback, filters: Filter = None, priority: int = 0)#

Handler for TemplateComponentsUpdate updates (Template components updates, e.g. when a template component is added or removed).

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

Example

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

Parameters:

callback – The callback function (Takes a WhatsApp instance and a TemplateComponentsUpdate as positional 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)#

Handler for raw updates (dicts) from the webhook.

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

Example

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

Parameters:

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

Handler Objects

Contents

Handler Objects#