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)¶ 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
namedentry_points
, is used to initiate the conversation, for example with atelegram.ext.CommandHandler
ortelegram.ext.RegexHandler
.The second collection, a
dict
namedstates
, 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 mostlytelegram.ext.MessageHandler
andtelegram.ext.RegexHandler
here.The third collection, a
list
namedfallbacks
, 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
namedtimed_out_behavior
is used if the wait forrun_async
takes longer than defined inrun_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 :attr`END` or-1
.-
entry_points
¶ List[
telegram.ext.Handler
] – A list ofHandler
objects that can trigger the start of the conversation.
-
states
¶ Dict[
object
, List[telegram.ext.Handler
]] – Adict
that defines the different states of conversation a user can be in and one or more associatedHandler
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 returnedFalse
oncheck_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 forrun_async
decorated Handlers.
-
timed_out_behavior
¶ List[
telegram.ext.Handler
] – Optional. A list of handlers that might be used if the wait forrun_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.
Parameters: - entry_points (List[
telegram.ext.Handler
]) – A list ofHandler
objects that can trigger the start of the conversation. The first handler whichcheck_update
method returnsTrue
will be used. If all returnFalse
, the update is not handled. - states (Dict[
object
, List[telegram.ext.Handler
]]) – Adict
that defines the different states of conversation a user can be in and one or more associatedHandler
objects that should be used in that state. The first handler whichcheck_update
method returnsTrue
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 returnedFalse
oncheck_update
. The first handler whichcheck_update
method returnsTrue
will be used. If all returnFalse
, the update is not handled. - allow_reentry (
bool
, optional) – If set toTrue
, 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 therun_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 isNone
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 forrun_async
timed out. The first handler whichcheck_update
method returnsTrue
will be used. If all returnFalse
, the update is not handled. - per_chat (
bool
, optional) – If the conversationkey should contain the Chat’s ID. Default isTrue
. - per_user (
bool
, optional) – If the conversationkey should contain the User’s ID. Default isTrue
. - per_message (
bool
, optional) – If the conversationkey should contain the Message’s ID. Default isFalse
.
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: - update (
telegram.Update
) – Incoming telegram update. - dispatcher (
telegram.ext.Dispatcher
) – Dispatcher that originated the Update.
- update (
-