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