Listeners reference

WhatsApp.listen(to: BaseListenerIdentifier, *, filters: Filter = None, cancelers: Filter = None, timeout: float | None = None) → BaseUpdate

Listen to an update.

• You can use one of the shortcuts to listen to a specific update type:

  • wait_for_reply()

  • wait_for_click()

  • wait_for_selection()

  • wait_for_completion()

  • wait_until_read()

  • wait_until_delivered()

Example

try:
    wa.send_message(
        to="123456",
        text="Send me a message",
        buttons=[Button(title="Cancel", callback_data="cancel")]
    )
    update: Message = wa.listen(
        to=UserUpdateListenerIdentifier(sender="123456", recipient="654321"),
        filters=filters.message & filters.text,
        cancelers=filters.callback_button & filters.matches("cancel"),
        timeout=10
    )
    print(update)
except ListenerTimeout:
    print("Listener timed out")
except ListenerCanceled:
    print("Listener was canceled")
except ListenerStopped:
    print("Listener was stopped")

Parameters:

• to – The identifier of the update to listen to.

• filters – The filters to apply to the update, return the update if the filters pass.

• cancelers – The filters to cancel the listening, raise ListenerCanceled if the update matches.

• timeout – The time to wait for the update, raise ListenerTimeout if the time passes

Returns:

The update that passed the filters

Raises:

• ListenerTimeout – If the listener timed out

• ListenerCanceled – If the listener was canceled by a filter

• ListenerStopped – If the listener was stopped manually

WhatsApp.stop_listening(to: BaseListenerIdentifier, *, reason: str | None = None) → None

Stop listening to updates for a specific listener

• Raising ListenerStopped to the listener

Parameters:

• to – The identifier of the listener to stop

• reason – The reason to stop listening

Raises:

ValueError – If the listener does not exist