Handler Objects

Handler Objects#

WhatsApp.add_handlers(*handlers)#

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 (Handler) – The handlers to add.

WhatsApp.add_flow_request_handler(handler)#

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 (FlowRequestHandler) – The flow request handler to add.
Returns:: A wrapper to help split the logic of the handler.
Return type:: FlowRequestCallbackWrapper

WhatsApp.remove_handlers(*handlers, silent=False)#

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 (Handler) – The handlers to remove.
silent (bool) – 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, filters=None, priority=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 (_MessageCallback) – The callback function (Takes the WhatsApp client instance and a Message as positional arguments).
filters (Filter) – The filters to apply to the callback
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.CallbackButtonHandler(callback, filters=None, factory=None, priority=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 (_CallbackButtonCallback) – The callback function. (Takes a WhatsApp instance and a CallbackButton as positional arguments)
filters (Filter) – The filters to apply to the handler
factory (type[CallbackData] | None) – The CallbackData constructor to use to construct the callback data.
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.CallbackSelectionHandler(callback, filters=None, factory=None, priority=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 (_CallbackSelectionCallback) – The callback function. (Takes a WhatsApp instance and a CallbackSelection as positional arguments)
filters (Filter) – The filters to apply to the handler
factory (type[CallbackData] | None) – The CallbackData constructor to use to construct the callback data.
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.FlowCompletionHandler(callback, filters=None, priority=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 (_FlowCompletionCallback) – The callback function (Takes a WhatsApp instance and a FlowCompletion as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.FlowRequestHandler(callback, *, endpoint, acknowledge_errors=True, private_key=None, private_key_password=None, request_decryptor=None, response_encryptor=None)#

A handler for Flow requests.

Parameters:

callback (_FlowRequestHandlerT) – 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 (str) – The endpoint to listen to (The endpoint uri you set to the flow. e.g /feedback_flow).
acknowledge_errors (bool) – Whether to acknowledge errors (The return value of the callback will be ignored, and pywa will acknowledge the error automatically).
private_key (str | None) – The private key to use to decrypt the requests (Override the global business_private_key).
private_key_password (str | None) – The password to use to decrypt the private key (Override the global business_private_key_password).
request_decryptor (utils.FlowRequestDecryptor | None) – The function to use to decrypt the requests (Override the global flows_request_decryptor)
response_encryptor (utils.FlowResponseEncryptor | None) – The function to use to encrypt the responses (Override the global flows_response_encryptor)

class pywa.handlers.MessageStatusHandler(callback, filters=None, factory=None, priority=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 (_MessageStatusCallback) – The callback function (Takes a WhatsApp instance and a MessageStatus as positional arguments).
filters (Filter) – The filters to apply to the handler
factory (type[CallbackData] | None) – The CallbackData constructor to use to construct the tracker data.
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.PhoneNumberChangeHandler(callback, filters=None, priority=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 (_PhoneNumberChangeCallback) – The callback function (Takes a WhatsApp instance and a PhoneNumberChange as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.IdentityChangeHandler(callback, filters=None, priority=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 (_IdentityChangeCallback) – The callback function (Takes a WhatsApp instance and a IdentityChange as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.CallConnectHandler(callback, filters=None, priority=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 (_CallConnectCallback) – The callback function (Takes a WhatsApp instance and a CallConnect as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.CallTerminateHandler(callback, filters=None, priority=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 (_CallTerminateCallback) – The callback function (Takes a WhatsApp instance and a CallTerminate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.CallStatusHandler(callback, filters=None, factory=None, priority=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 (_CallStatusCallback) – The callback function (Takes a WhatsApp instance and a CallStatus as positional arguments)
filters (Filter) – The filters to apply to the handler
factory (type[CallbackData] | None) – The CallbackData constructor to use to construct the tracker data.
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.CallPermissionUpdateHandler(callback, filters=None, priority=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 (_CallPermissionUpdateCallback) – The callback function (Takes a WhatsApp instance and a CallPermissionUpdate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.UserMarketingPreferencesHandler(callback, filters=None, priority=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 (_UserMarketingPreferencesCallback) – The callback function (Takes a WhatsApp instance and a UserMarketingPreferences as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.TemplateStatusUpdateHandler(callback, filters=None, priority=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 (_TemplateStatusUpdateCallback) – The callback function (Takes a WhatsApp instance and a TemplateStatusUpdate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.TemplateCategoryUpdateHandler(callback, filters=None, priority=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 (_TemplateCategoryUpdateCallback) – The callback function (Takes a WhatsApp instance and a TemplateCategoryUpdate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.TemplateQualityUpdateHandler(callback, filters=None, priority=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 (_TemplateQualityUpdateCallback) – The callback function (Takes a WhatsApp instance and a TemplateQualityUpdate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.TemplateComponentsUpdateHandler(callback, filters=None, priority=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 (_TemplateComponentsUpdateCallback) – The callback function (Takes a WhatsApp instance and a TemplateComponentsUpdate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

class pywa.handlers.EditedMessageHandler(callback, filters=None, priority=0)#

Handler for EditedMessage updates (When a user edits a message).

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

Example

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

Parameters:

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

class pywa.handlers.DeletedMessageHandler(callback, filters=None, priority=0)#

Handler for DeletedMessage updates (When a user revokes a message).

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

Example

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

Parameters:

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

class pywa.handlers.OutgoingMessageHandler(callback, filters=None, priority=0)#

Handler for OutgoingMessage updates (When you send a message using the WhatsApp Business App)

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

Example

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

Parameters:

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

class pywa.handlers.OutgoingEditedMessageHandler(callback, filters=None, priority=0)#

Handler for OutgoingEditedMessage updates (When you edit a message using the WhatsApp Business App)

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

Example

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

Parameters:

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

class pywa.handlers.OutgoingDeletedMessageHandler(callback, filters=None, priority=0)#

Handler for OutgoingDeletedMessage updates (When you revoke a message using the WhatsApp Business App)

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

Example

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

Parameters:

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

class pywa.handlers.RawUpdateHandler(callback, filters=None, priority=0)#

Handler for raw updates 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 (_RawUpdateCallback) – The callback function (Takes a WhatsApp instance and a RawUpdate as positional arguments)
filters (Filter) – The filters to apply to the handler
priority (int) – The priority of the handler (default: 0)

Handler Objects

Contents

Handler Objects#