Hide navigation sidebar
Hide table of contents sidebar
PTB has undergone significant changes in v20. Please read the documentation carefully and also check out the transition guide in the wiki.
Back to top
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

  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`

  Available In

  `telegram.ext.Application.handlers`

  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`]]