Handler Decorators#

WhatsApp.on_message(filters: Filter = None, priority: int = 0) → Callable[[_MessageCallback], _MessageCallback] | _MessageCallback#

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 import WhatsApp, types, filters
>>> wa = WhatsApp(...)
>>> @wa.on_message(filters.matches("Hello", "Hi", ignore_case=True))
... def hello_handler(_: WhatsApp, msg: types.Message):
...     msg.react("👋")
...     msg.reply_text(text="Hello from PyWa!", quote=True)

Parameters:

filters – Filters to apply to the incoming messages.
priority – The priority of the handler (default: 0).

WhatsApp.on_callback_button(filters: Filter = None, factory: type[CallbackData] | None = None, priority: int = 0) → Callable[[_CallbackButtonCallback], _CallbackButtonCallback] | _CallbackButtonCallback#

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 import WhatsApp, types, filters
>>> wa = WhatsApp(...)
>>> @wa.on_callback_button(filters.matches("help"))
... def help_handler(_: WhatsApp, btn: types.CallbackButton):
...     btn.reply_text(text="What can I help you with?")

Parameters:

filters – Filters to apply to the incoming callback button presses.
factory – The constructor to use to construct the callback data.
priority – The priority of the handler (default: 0).

WhatsApp.on_callback_selection(filters: Filter = None, factory: type[CallbackData] | None = None, priority: int = 0) → Callable[[_CallbackSelectionCallback], _CallbackSelectionCallback] | _CallbackSelectionCallback#

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 import WhatsApp, types, filters
>>> wa = WhatsApp(...)
>>> @wa.on_callback_selection(filters.startswith("id:"))
... def id_handler(_: WhatsApp, sel: types.CallbackSelection):
...     sel.reply_text(text=f"Your ID is {sel.data.split(':', 1)[1]}")

Parameters:

filters – Filters to apply to the incoming callback selections.
factory – The constructor to use to construct the callback data.
priority – The priority of the handler (default: 0).

WhatsApp.on_flow_completion(filters: Filter = None, priority: int = 0) → Callable[[_FlowCompletionCallback], _FlowCompletionCallback] | _FlowCompletionCallback#

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 import WhatsApp, types
>>> wa = WhatsApp(...)
>>> @wa.on_flow_completion
... def flow_handler(client: WhatsApp, flow: types.FlowCompletion):
...     print(f"Flow {flow.token} just got completed!. Flow data: {flow.response}")

Parameters:

filters – Filters to apply to the incoming flow completion.
priority – The priority of the handler (default: 0).

WhatsApp.on_flow_request(endpoint: str = None, *, 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[[_FlowRequestHandlerT], FlowRequestCallbackWrapper | FlowRequestHandler]#

Decorator to register a function to handle and respond to incoming flow requests.

Example

>>> from pywa import WhatsApp, types
>>> wa = WhatsApp(business_private_key='...', ...)
>>> @wa.on_flow_request('/feedback_flow')
... def feedback_flow_handler(_: WhatsApp, req: FlowRequest) -> FlowResponse:
...     ...

>>> @feedback_flow_handler.on(types.FlowRequestActionType.DATA_EXCHANGE, screen="SURVEY")
... def survey_data_handler(_: WhatsApp, req: FlowRequest):
...     ...

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: Filter = None, factory: type[CallbackData] | None = None, priority: int = 0) → Callable[[_MessageStatusCallback], _MessageStatusCallback] | _MessageStatusCallback#

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 import WhatsApp, types, filters
>>> wa = WhatsApp(...)
>>> @wa.on_message_status(filters.failed)
... def delivered_handler(client: WhatsApp, status: types.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.
factory – The constructor to use to construct the callback data.
priority – The priority of the handler (default: 0).

WhatsApp.on_chat_opened(filters: Filter = None, priority: int = 0) → Callable[[_ChatOpenedCallback], _ChatOpenedCallback] | _ChatOpenedCallback#

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 import WhatsApp, types
>>> wa = WhatsApp(...)
>>> @wa.on_chat_opened
... def chat_opened_handler(client: WhatsApp, chat_opened: types.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.
priority – The priority of the handler (default: 0).

WhatsApp.on_template_status(filters: Filter = None, priority: int = 0) → Callable[[_TemplateStatusCallback], _TemplateStatusCallback] | _TemplateStatusCallback#

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 import WhatsApp, types, filters
>>> wa = WhatsApp(...)
>>> @wa.on_template_status
... def approved_handler(client: WhatsApp, status: types.TemplateStatus):
...     print(f"Template {status.message_template_name} just got {status.event}!")

Parameters:

filters – Filters to apply to the incoming template status changes.
priority – The priority of the handler (default: 0).

WhatsApp.on_raw_update(filters: Filter = None, priority: int = 0) → Callable[[_RawUpdateCallback], _RawUpdateCallback] | _RawUpdateCallback#

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

WhatsApp.remove_callbacks(*callbacks: Callable[[WhatsApp, Any], Any]) → None#

Remove callbacks programmatically (not flow callbacks).

Example

>>> from pywa.handlers import MessageHandler, CallbackButtonHandler
>>> from pywa import filters as fil
>>> wa = WhatsApp(...)
>>> @wa.on_message(fil.text)
... def message_handler(_: WhatsApp, msg: Message): print(msg)
>>> wa.remove_callbacks(message_handler)

Parameters:: callbacks – The callbacks to remove.

WhatsApp.load_handlers_modules(*modules: ModuleType) → None#

Load handlers from modules.

Example

my_handlers.py#

from pywa import WhatsApp, types, filters as fil

@WhatsApp.on_message(fil.text)
def on_text_message(wa: WhatsApp, msg: types.Message):
    ...

@WhatsApp.on_callback_button
def on_callback_button(wa: WhatsApp, msg: types.CallbackButton):
    ...

main.py#

from pywa import WhatsApp
from . import my_handlers

wa = WhatsApp(..., handlers_modules=[my_handlers])

Handler Decorators

Contents

Handler Decorators#