telegram.ext.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)¶

Bases: telegram.ext.handler.Handler

A handler to hold a conversation with a single user by managing four collections of other handlers.

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

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 @run_async decorated 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.

Note

In each of the described collections of handlers, a handler may in turn be a ConversationHandler. In that case, the nested ConversationHandler should have the attribute map_to_parent which allows to return to the parent conversation at specified states within the nested 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 this has ended or even map a state to END to end the parent conversation from within the nested one. For an example on nested ConversationHandler s, see our examples.

entry_points¶

A list of Handler objects that can trigger the start of the conversation.

Type:	List[`telegram.ext.Handler`]

states¶

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

Type:	Dict[`object`, List[`telegram.ext.Handler`]]

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

allow_reentry¶

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

Type:	`bool`

per_chat¶

If the conversationkey should contain the Chat’s ID.

Type:	`bool`

per_user¶

If the conversationkey should contain the User’s ID.

Type:	`bool`

per_message¶

If the conversationkey should contain the Message’s ID.

Type:	`bool`

conversation_timeout¶

Optional. When this handler is inactive more than this timeout (in seconds), it will be automatically ended. If this value is 0 (default), there will be no timeout. When it’s triggered, the last received update will be handled by ALL the handler’s who’s check_update method returns True that are in the state ConversationHandler.TIMEOUT.

Type:	float`\|:obj:`datetime.timedelta

name¶

Optional. The name for this conversationhandler. Required for persistence

Type:	`str`

persistent¶

Optional. If the conversations dict for this handler should be saved. Name is required and persistence has to be set in telegram.ext.Updater

Type:	`bool`

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

Parameters:

entry_points (List[telegram.ext.Handler]) – A list of Handler objects that can trigger the start of the conversation. The first handler which check_update method returns True will be used. If all return False, the update is not handled.
states (Dict[object, List[telegram.ext.Handler]]) – A dict that defines the different states of conversation a user can be in and one or more associated Handler objects that should be used in that state. The first handler which check_update method returns True will be used.
fallbacks (List[telegram.ext.Handler]) – 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.
per_chat (bool, optional) – If the conversationkey should contain the Chat’s ID. Default is True.
per_user (bool, optional) – If the conversationkey should contain the User’s ID. Default is True.
per_message (bool, optional) – If the conversationkey 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 will be handled by ALL the handler’s who’s check_update method returns True that are in the state ConversationHandler.TIMEOUT.
name (str, optional) – The name for this conversationhandler. Required for persistence
persistent (bool, optional) – If the conversations dict for this handler should be saved. Name is required and persistence has to be set in telegram.ext.Updater
map_to_parent (Dict[object, object], 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.

Raises:

ValueError

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.

Type:	`int`

WAITING = -3¶

Used as a constant to handle state when a conversation is still waiting on the previous @run_sync decorated running handler to finish.

Type:	`int`

check_update(update)¶

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

Parameters:	update (`telegram.Update`) – Incoming telegram update.
Returns:	`bool`

handle_update(update, dispatcher, check_result, context=None)¶

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

Parameters:	check_result – The result from check_update. For this handler it’s a tuple of key, handler, and the handler’s check result. update (`telegram.Update`) – Incoming telegram update. dispatcher (`telegram.ext.Dispatcher`) – Dispatcher that originated the Update.