Ctrl+K

Handler Objects

Handler Objects#

WhatsApp.add_handlers(*handlers: Handler)#

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),
... )
class pywa.handlers.MessageHandler(handler: Callable[[WhatsApp, Message], Any], *filters: Callable[[WhatsApp, Message], bool])#

Handler for incoming pywa.types.Message.

  • You can use the on_message() decorator to register a handler 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:

  • handler – The handler function (gets the pywa.WhatsApp instance and a pywa.types.Message as arguments)

  • *filters – The filters to apply to the handler (gets a pywa.WhatsApp instance and a pywa.types.Message and returns a bool)

class pywa.handlers.CallbackButtonHandler(handler: Callable[[WhatsApp, CallbackButton], Any], *filters: Callable[[WhatsApp, CallbackButton], bool], factory: CallbackDataT = <class 'str'>)#

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

IMPORTANT: If factory provided, The filters have no access to the constructed callback data, only the raw string (When subclassing pywa.types.CallbackData as the factory, a matching filter is automatically added, so there is no need to add it manually).

Example

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

  • handler – The handler function (gets the WhatsApp instance and the callback as arguments)

  • *filters – The filters to apply to the handler (gets 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).

class pywa.handlers.CallbackSelectionHandler(handler: Callable[[WhatsApp, CallbackSelection], Any], *filters: Callable[[WhatsApp, CallbackSelection], bool], factory: CallbackDataT = <class 'str'>)#

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

IMPORTANT: If factory provided, The filters have no access to the constructed callback data, only the raw string (When subclassing pywa.types.CallbackData as the factory, a matching filter is automatically added, so there is no need to add it manually).

Example

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

  • handler – The handler function. (gets a pywa.WhatsApp instance and a pywa.types.CallbackSelection as arguments)

  • *filters – The filters to apply to the handler. (gets 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).

class pywa.handlers.MessageStatusHandler(handler: Callable[[WhatsApp, MessageStatus], Any], *filters: Callable[[WhatsApp, MessageStatus], bool])#

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

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:

  • handler – The handler function (gets a pywa.WhatsApp instance and a pywa.types.MessageStatus as arguments)

  • *filters – The filters to apply to the handler (gets a pywa.WhatsApp instance and a pywa.types.MessageStatus and returns a bool)

class pywa.handlers.TemplateStatusHandler(handler: Callable[[WhatsApp, TemplateStatus], Any], *filters: Callable[[WhatsApp, TemplateStatus], bool])#

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

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:
class pywa.handlers.RawUpdateHandler(handler: Callable[[WhatsApp, dict], Any], *filters: Callable[[WhatsApp, dict], bool])#

A raw update handler.

  • 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 handler function (gets a pywa.WhatsApp instance and a dict as arguments)

  • *filters – The filters to apply to the handler (gets a pywa.WhatsApp instance and a dict and returns a bool)

Contents