register_next_step_handler()

async Client.register_next_step_handler()

Run a callback once, on the next update matching the given criteria.

The callback form of listen(), for flows that would rather not park a coroutine. It does not hold a dispatcher worker, so it scales further than listen for long or abandoned conversations.

Usable by Users Bots
Parameters:

  • callback (Callable) – Called with (client, update) when a matching update arrives. May be a coroutine function or a plain one.

  • 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 before the listener is dropped. Defaults to the client’s listener_timeout (300s). Pass None to keep it forever.

  • 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:

Listener – The registered listener, which can be handed to stop_listening() criteria or dropped with client.listeners.stop(listener).

Raises:

  • ListenerStopped – In case the client is stopping.

  • ListenerLimitReached – In case no listener slot was available.

Example

async def got_name(client, message):
    await message.reply(f"Hello {message.text}")

await app.send_message(chat_id, "What is your name?")
await app.register_next_step_handler(got_name, chat_id=chat_id)