telegram.ext.ConversationHandler

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

Bases: telegram.ext.handler.Handler

A handler to hold a conversation with a single user by managing four collections of other handlers. Note that neither posts in Telegram Channels, nor group interactions with multiple users are managed by instances of this class.

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. You will probably use mostly telegram.ext.MessageHandler and telegram.ext.RegexHandler here.

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.

The fourth, optional collection of handlers, a list named timed_out_behavior is used if the wait for run_async takes longer than defined in run_async_timeout. For example, you can let the user know that they should wait for a bit before they can continue.

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. To end the conversation, the callback function must return END or -1.

entry_points

List[telegram.ext.Handler] – A list of Handler objects that can trigger the start of the conversation.

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.

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.

allow_reentry

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

run_async_timeout

float – Optional. The time-out for run_async decorated Handlers.

timed_out_behavior

List[telegram.ext.Handler] – Optional. A list of handlers that might be used if the wait for run_async timed out.

per_chat

bool – Optional. If the conversationkey should contain the Chat’s ID.

per_user

bool – Optional. If the conversationkey should contain the User’s ID.

per_message

bool – Optional. If the conversationkey should contain the Message’s ID.

conversation_timeout

float`|:obj:`datetime.timedelta – 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.

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

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.
  • run_async_timeout (float, optional) – If the previous handler for this user was running asynchronously using the run_async decorator, it might not be finished when the next message arrives. This timeout defines how long the conversation handler should wait for the next state to be computed. The default is None which means it will wait indefinitely.
  • timed_out_behavior (List[telegram.ext.Handler], optional) – A list of handlers that might be used if the wait for run_async timed out. The first handler which check_update method returns True will be used. If all return False, the update is not handled.
  • 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`|:obj:`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.
  • 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
Raises:

ValueError

END = -1

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

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)

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

Parameters:
persistence = None

telegram.ext.BasePersistance – The persistence used to store conversations. Set by dispatcher