listen()

async Client.listen()

Wait for the next update matching the given criteria.

The update is consumed: handlers do not see it. Raw update handlers still do, since they are a separate contract.

Usable by Users Bots
Parameters:

  • filters (Filter, optional) – Extra filter the update has to pass.

  • listener_type (ListenerTypes, optional) – Kind of update to wait for. Defaults to a new message.

  • timeout (float, optional) – Seconds to wait before raising ListenerTimeout. Defaults to the client’s listener_timeout (300s). Pass None to wait forever, which leaks a listener per abandoned conversation.

  • unallowed_click_alert (bool | str, optional) – For callback query listeners, answer clicks coming from a user this listener does not expect. Pass a string to set the text.

  • chat_id (int | str | List of int | str, optional) – Chat the update has to come from.

  • user_id (int | str | List of int | str, optional) – User the update has to come from.

  • message_id (int | List of int, optional) – Message the update has to belong to.

  • inline_message_id (str | List of str, optional) – Inline message the update has to belong to.

Returns:

Message | CallbackQuery – The matching update.

Raises:

  • ListenerTimeout – In case no matching update arrived in time.

  • ListenerStopped – In case the listener was stopped, or the client is.

  • ListenerLimitReached – In case no listener slot was available.

Example

# Wait for the next message in a chat
message = await app.listen(chat_id=chat_id)

# Wait up to 60s for one specific user, ignoring everyone else
reply = await app.listen(chat_id=chat_id, user_id=user_id, timeout=60)

# Wait for a button press on a message you just sent
query = await app.listen(
    listener_type=enums.ListenerTypes.CALLBACK_QUERY,
    chat_id=chat_id,
    message_id=sent.id
)