Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# ConversationHandler

class telegram.ext.ConversationHandler(entry_points, states, fallbacks, allow_reentry=False, per_chat=True, per_user=True, per_message=False, conversation_timeout=None, name=None, persistent=False, map_to_parent=None, block=True)

  Bases: `telegram.ext.BaseHandler`

  A handler to hold a conversation with a single or multiple users through Telegram updates by managing three collections of other handlers.

  Warning

  `ConversationHandler` heavily relies on incoming updates being processed one by one. When using this handler, `telegram.ext.ApplicationBuilder.concurrent_updates` should be set to `False`.

  Note

  `ConversationHandler` will only accept updates that are (subclass-)instances of `telegram.Update`. This is, because depending on the `per_user` and `per_chat`, `ConversationHandler` relies on `telegram.Update.effective_user` and/or `telegram.Update.effective_chat` in order to determine which conversation an update should belong to. For `per_message=True`, `ConversationHandler` uses `update.callback_query.message.message_id` when `per_chat=True` and `update.callback_query.inline_message_id` when `per_chat=False`. For a more detailed explanation, please see our FAQ.

  Finally, `ConversationHandler`, does not handle (edited) channel posts.

  The first collection, a `list` named `entry_points`, is used to initiate the conversation, for example with a `telegram.ext.CommandHandler` or `telegram.ext.MessageHandler`.

  The second collection, a `dict` named `states`, contains the different conversation steps and one or more associated handlers that should be used if the user sends a message when the conversation with them is currently in that state. Here you can also define a state for `TIMEOUT` to define the behavior when `conversation_timeout` is exceeded, and a state for `WAITING` to define behavior when a new update is received while the previous `block=False` handler is not finished.

  The third collection, a `list` named `fallbacks`, is used if the user is currently in a conversation but the state has either no associated handler or the handler that is associated to the state is inappropriate for the update, for example if the update contains a command, but a regular text message is expected. You could use this for a `/cancel` command or to let the user know their message was not recognized.

  To change the state of conversation, the callback function of a handler must return the new state after responding to the user. If it does not return anything (returning `None` by default), the state will not change. If an entry point callback function returns `None`, the conversation ends immediately after the execution of this callback function. To end the conversation, the callback function must return `END` or `-1`. To handle the conversation timeout, use handler `TIMEOUT` or `-2`. Finally, `telegram.ext.ApplicationHandlerStop` can be used in conversations as described in its documentation.

  Note

  In each of the described collections of handlers, a handler may in turn be a `ConversationHandler`. In that case, the child `ConversationHandler` should have the attribute `map_to_parent` which allows returning to the parent conversation at specified states within the child conversation.

  Note that the keys in `map_to_parent` must not appear as keys in `states` attribute or else the latter will be ignored. You may map `END` to one of the parents states to continue the parent conversation after the child conversation has ended or even map a state to `END` to end the parent conversation from within the child conversation. For an example on nested `ConversationHandler` s, see nestedconversationbot.py.

  Examples

  - Conversation Bot

  - Conversation Bot 2

  - Nested Conversation Bot

  - Persistent Conversation Bot

  Available In

  - `telegram.ext.Application.handlers`

  - `telegram.ext.ConversationHandler.name`

  Parameters:

    - entry_points (list[`telegram.ext.BaseHandler`]) – A list of `BaseHandler` objects that can trigger the start of the conversation. The first handler whose `check_update()` method returns `True` will be used. If all return `False`, the update is not handled.

    - states (dict[`object`, list[`telegram.ext.BaseHandler`]]) – A `dict` that defines the different states of conversation a user can be in and one or more associated `BaseHandler` objects that should be used in that state. The first handler whose `check_update()` method returns `True` will be used.

    - fallbacks (list[`telegram.ext.BaseHandler`]) – A list of handlers that might be used if the user is in a conversation, but every handler for their current state returned `False` on `check_update()`. The first handler which `check_update()` method returns `True` will be used. If all return `False`, the update is not handled.

    - allow_reentry (`bool`, optional) – If set to `True`, a user that is currently in a conversation can restart the conversation by triggering one of the entry points. Default is `False`.

    - per_chat (`bool`, optional) – If the conversation key should contain the Chat’s ID. Default is `True`.

    - per_user (`bool`, optional) – If the conversation key should contain the User’s ID. Default is `True`.

    - per_message (`bool`, optional) – If the conversation key should contain the Message’s ID. Default is `False`.

    - conversation_timeout (`float` | `datetime.timedelta`, optional) –

      When this handler is inactive more than this timeout (in seconds), it will be automatically ended. If this value is `0` or `None` (default), there will be no timeout. The last received update and the corresponding `context` will be handled by ALL the handler’s whose `check_update()` method returns `True` that are in the state `ConversationHandler.TIMEOUT`.

      Caution

      - This feature relies on the `telegram.ext.Application.job_queue` being set and hence requires that the dependencies that `telegram.ext.JobQueue` relies on are installed.

      - Using `conversation_timeout` with nested conversations is currently not supported. You can still try to use it, but it will likely behave differently from what you expect.

    - name (`str`, optional) – The name for this conversation handler. Required for persistence.

    - persistent (`bool`, optional) –

      If the conversation’s dict for this handler should be saved. `name` is required and persistence has to be set in `Application`.

      Changed in version 20.0: Was previously named as `persistence`.

    - map_to_parent (dict[`object`, `object`], optional) – A `dict` that can be used to instruct a child conversation handler to transition into a mapped state on its parent conversation handler in place of a specified nested state.

    - block (`bool`, optional) –

      Pass `False` or `True` to set a default value for the `BaseHandler.block` setting of all handlers (in `entry_points`, `states` and `fallbacks`). The resolution order for checking if a handler should be run non-blocking is:

      1. `telegram.ext.BaseHandler.block` (if set)

      2. the value passed to this parameter (if any)

      3. `telegram.ext.Defaults.block` (if defaults are used)

      See also

      Concurrency

      Changed in version 20.0: No longer overrides the handlers settings. Resolution order was changed.

  Raises:

    ValueError – If `persistent` is used but `name` was not set, or when `per_message`, `per_chat`, `per_user` are all `False`.

  block

    Determines whether the callback will run in a blocking way. Always `True` since conversation handlers handle any non-blocking callbacks internally.

    Type:

      `bool`

  END = -1

    Used as a constant to return when a conversation is ended.

    Type:

      `int`

  TIMEOUT = -2

    Used as a constant to handle state when a conversation is timed out (exceeded `conversation_timeout`).

    Type:

      `int`

  WAITING = -3

    Used as a constant to handle state when a conversation is still waiting on the previous `block=False` handler to finish.

    Type:

      `int`

  __repr__()

    Give a string representation of the ConversationHandler in the form `ConversationHandler[name=..., states={...}]`.

    If there are more than 3 states, only the first 3 states are listed.

    As this class doesn’t implement `object.__str__()`, the default implementation will be used, which is equivalent to `__repr__()`.

    Returns:

      `str`

  property allow_reentry

    Determines if a user can restart a conversation with an entry point.

    Type:

      `bool`

  check_update(update)

    Determines whether an update should be handled by this conversation handler, and if so in which state the conversation currently is.

    Parameters:

      update (`telegram.Update` | `object`) – Incoming update.

    Returns:

      `bool`

  property conversation_timeout

    Optional. When this handler is inactive more than this timeout (in seconds), it will be automatically ended.

    Type:

      `float` | `datetime.timedelta`

  property entry_points

    A list of `BaseHandler` objects that can trigger the start of the conversation.

    Type:

      list[`telegram.ext.BaseHandler`]

  property fallbacks

    A list of handlers that might be used if the user is in a conversation, but every handler for their current state returned `False` on `check_update()`.

    Type:

      list[`telegram.ext.BaseHandler`]

  async handle_update(update, application, check_result, context)

    Send the update to the callback for the current state and BaseHandler

    Parameters:

      - check_result – The result from `check_update()`. For this handler it’s a tuple of the conversation state, key, handler, and the handler’s check result.

      - update (`telegram.Update`) – Incoming telegram update.

      - application (`telegram.ext.Application`) – Application that originated the update.

      - context (`telegram.ext.CallbackContext`) – The context as provided by the application.

  property map_to_parent

    Optional. A `dict` that can be used to instruct a nested `ConversationHandler` to transition into a mapped state on its parent `ConversationHandler` in place of a specified nested state.

    Type:

      dict[`object`, `object`]

  property name

    Optional. The name for this `ConversationHandler`.

    Type:

      `str`

  property per_chat

    If the conversation key should contain the Chat’s ID.

    Type:

      `bool`

  property per_message

    If the conversation key should contain the message’s ID.

    Type:

      `bool`

  property per_user

    If the conversation key should contain the User’s ID.

    Type:

      `bool`

  property persistent

    Optional. If the conversations dict for this handler should be saved. `name` is required and persistence has to be set in `Application`.

    Type:

      `bool`

  property states

    A `dict` that defines the different states of conversation a user can be in and one or more associated `BaseHandler` objects that should be used in that state.

    Type:

      dict[`object`, list[`telegram.ext.BaseHandler`]]