Handler Objects#
- WhatsApp.add_handlers(*handlers: Handler | FlowRequestHandler)#
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.remove_handlers(*handlers: Handler)#
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.
- Raises:
ValueError β If the handler is not registered.
- WhatsApp.remove_callbacks(*callbacks: Callable[[WhatsApp, Any], Any])#
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.
- class pywa.handlers.MessageHandler(callback: 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 callback 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:
callback β The callback function (Takes the
pywa.WhatsApp
instance and apywa.types.Message
as arguments)*filters β The filters to apply to the callback (Takes a
pywa.WhatsApp
instance and apywa.types.Message
and returns abool
)
- class pywa.handlers.CallbackButtonHandler(callback: Callable[[WhatsApp, CallbackButton], Any], *filters: Callable[[WhatsApp, CallbackButton], bool], factory: CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False)#
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 as fil >>> wa = WhatsApp(...) >>> print_btn = lambda _, btn: print(btn) >>> wa.add_handlers(CallbackButtonHandler(print_btn, fil.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 apywa.types.CallbackButton
and returns abool
)factory β The constructor/s to use to construct the callback data (default:
str
. If the factory is a subclass ofCallbackData
, a matching filter is automatically added).factory_before_filters β Whether to apply the factory before the filters (default:
False
. IfTrue
, the filters will get the callback data after the factory is applied).
- class pywa.handlers.CallbackSelectionHandler(callback: Callable[[WhatsApp, CallbackSelection], Any], *filters: Callable[[WhatsApp, CallbackSelection], bool], factory: CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False)#
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 as fil >>> wa = WhatsApp(...) >>> print_selection = lambda _, sel: print(sel) >>> wa.add_handlers(CallbackSelectionHandler(print_selection, fil.startswith('id:')))
- Parameters:
callback β The callback function. (Takes a
pywa.WhatsApp
instance and apywa.types.CallbackSelection
as arguments)*filters β The filters to apply to the handler. (Takes a
pywa.WhatsApp
instance and apywa.types.CallbackSelection
and returns abool
)factory β The constructor/s to use to construct the callback data (default:
str
. If the factory is a subclass ofCallbackData
, a matching filter is automatically added).factory_before_filters β Whether to apply the factory before the filters (default:
False
. IfTrue
, the filters will get the callback data after the factory is applied).
- class pywa.handlers.FlowCompletionHandler(callback: Callable[[WhatsApp, FlowCompletion], Any], *filters: Callable[[WhatsApp, FlowCompletion], bool])#
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 apywa.types.FlowCompletion
as arguments)
- class pywa.handlers.FlowRequestHandler(callback: Callable[[WhatsApp, FlowRequest], FlowResponse | FlowResponseError | dict | None], *, 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 apywa.types.FlowRequest
as arguments and returns apywa.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: Callable[[WhatsApp, MessageStatus], Any], *filters: Callable[[WhatsApp, MessageStatus], bool], factory: CallbackDataFactoryT = <class 'str'>, factory_before_filters: bool = False)#
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, filters as fil >>> wa = WhatsApp(...) >>> print_failed_messages = lambda _, msg: print(msg) >>> wa.add_handlers(MessageStatusHandler(print_failed_messages, fil.message_status.failed))
- Parameters:
callback β The callback function (Takes a
pywa.WhatsApp
instance and apywa.types.MessageStatus
as arguments)*filters β The filters to apply to the handler (Takes a
pywa.WhatsApp
instance and apywa.types.MessageStatus
and returns abool
)factory β The constructor/s to use to construct the tracker data (default:
str
. If the factory is a subclass ofCallbackData
, a matching filter is automatically added).factory_before_filters β Whether to apply the factory before the filters (default:
False
. IfTrue
, the filters will get the tracker data after the factory is applied).
- class pywa.handlers.ChatOpenedHandler(callback: Callable[[WhatsApp, ChatOpened], Any], *filters: Callable[[WhatsApp, ChatOpened], bool])#
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 apywa.types.ChatOpened
as arguments)*filters β The filters to apply to the handler (Takes a
pywa.WhatsApp
instance and apywa.types.ChatOpened
and returns abool
)
- class pywa.handlers.TemplateStatusHandler(callback: Callable[[WhatsApp, TemplateStatus], Any], *filters: Callable[[WhatsApp, TemplateStatus], bool])#
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, 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:
callback β The callback function (Takes a
pywa.WhatsApp
instance and apywa.types.TemplateStatus
as arguments)*filters β The filters to apply to the handler (Takes a
pywa.WhatsApp
instance and apywa.types.TemplateStatus
and returns abool
)
- class pywa.handlers.RawUpdateHandler(callback: Callable[[WhatsApp, dict], Any], *filters: Callable[[WhatsApp, dict], bool])#
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))