Listeners reference

Listeners reference#

WhatsApp.listen(to: str | int, filters: Filter = None, cancelers: Filter = None, timeout: int | None = None, sent_to_phone_id: str | int | None = None) → _SuppoertedUserUpdate

Listen to a user update

Example

try:
    wa.send_message(
        to="123456",
        text="Send me a message",
        buttons=[Button(title="Cancel", callback_data="cancel")]
    )
    update: Message = wa.listen(
        to="123456",
        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 user 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

  • sent_to_phone_id – The phone id to listen for

Returns:

The update that passed the filters

Raises:
WhatsApp.stop_listening(to: str | int, reason: str | None = None, phone_id: str | int | None = None) → None
Stop listening to a user.

  • Raising ListenerStopped to the listener

Parameters:

  • to – The user that the listener is listening to

  • reason – The reason to stop listening

  • phone_id – The phone id that the listener is listening for

Raises:

ValueError – If the listener does not exist

SentMessage.wait_for_reply(force_quote: bool = False, filters: Filter = None, cancelers: Filter = None, timeout: int | None = None) → Message#

Wait for a message reply to the sent message.

  • Shortcut for listen() with filters=filters.message.

Example

@wa.on_message(filters.command("start"))
def start(w: WhatsApp, m: Message):
    user_id: str = m.reply(
        text=f"Hi {m.from_user.name}! Please enter your ID",
        buttons=[Button(title="Cancel", callback_data="cancel")],
    ).wait_for_reply(
        filters=filters.text,
        cancelers=filters.callback_button & filters.matches("cancel"),
    ).text
    ...
Parameters:

  • force_quote – Whether to force the reply to quote the sent message.

  • filters – The filters to apply to the reply.

  • cancelers – The filters to cancel the listening.

  • timeout – The time to wait for a reply.

Returns:

The reply message.

Raises:
SentMessage.wait_for_click(force_options: bool = True, filters: Filter = None, cancelers: Filter = None, timeout: int | None = None) → CallbackButton#

Wait for a button click.

Example

@wa.on_message(filters.command("start"))
def start(w: WhatsApp, m: Message):
    r = m.reply(
        text="Click a button",
        buttons=[
            Button(title="Option 1", callback_data="option1"),
            Button(title="Option 2", callback_data="option2"),
        ],
    )
    option = r.wait_for_click()
    r.reply(f"You clicked: {option.title}", quote=True)
Parameters:

  • force_options – Whether to force the button to be one of the sent buttons.

  • filters – The filters to apply to the button click.

  • cancelers – The filters to cancel the listening.

  • timeout – The time to wait for the button click.

Returns:

The clicked button.

Raises:
SentMessage.wait_for_selection(force_options: bool = True, filters: Filter = None, cancelers: Filter = None, timeout: int | None = None) → CallbackSelection#

Wait for a callback selection.

Parameters:

  • force_options – Whether to force the selection to be one of the sent rows.

  • filters – The filters to apply to the selection.

  • cancelers – The filters to cancel the listening.

  • timeout – The time to wait for the selection.

Returns:

The callback selection.

Raises:
SentMessage.wait_until_read(cancel_on_new_update: bool = False, cancelers: Filter = None, timeout: int | None = None) → MessageStatus#

Wait for the message to be read by the recipient.

  • Shortcut for listen() with filters=filters.message_status & filters.read.

Note: This method will not work if the recipient has disabled read receipts. make sure to use cancel_on_new_update=True to cancel the listening if the message is probably read, or use a timeout / cancelers.

Example

@wa.on_message(filters.command("start"))
def start(w: WhatsApp, m: Message):
    r = m.reply("This message waits for you to read it")
    try:
        r.wait_until_read(cancel_on_new_update=True)
    except ListenerCanceled as e:
        print(e.update) # The update that canceled the listener
        r.reply("You turned off read receipts")
    r.reply("You read this message", quote=True)
Parameters:

  • cancel_on_new_update – Whether to cancel when another user update arrives (which may indicate the previous message was read).

  • cancelers – The filters to cancel the listening.

  • timeout – The time to wait for the message to be read.

Returns:

The message status.

Raises:
SentMessage.wait_until_delivered(cancelers: Filter = None, timeout: int | None = None) → MessageStatus#

Wait for the message to be delivered to the recipient.

Example

@wa.on_message(filters.command("start"))
def start(w: WhatsApp, m: Message):
    r = m.reply("This message waits for you to receive it")
    r.wait_until_delivered()
    r.reply("You received the message", quote=True)
Parameters:

  • cancelers – The filters to cancel the listening.

  • timeout – The time to wait for the message to be delivered.

Returns:

The message status.

Raises: