To hold a conversation with users, the bot has to implement a state machine to keep track of the different paths in the conversation. This is a pretty common pattern and we don't have a good way to deal with it right now. The state_machine_bot.py example is far from perfect.

This PR introduces a new Handler subclass called ConversationHandler to take care of this. Instead of re-inventing the wheel, this handler acts only as "management" for the existing handler classes.

Copied from documentation:

A handler to hold a conversation with a 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 CommandHandler or 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
MessageHandler and 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 CallbackHandler.END or -1.

Usage (copied from example):

ConversationHandler(
    entry_points=[CommandHandler('start', start)],

    states={
        GENDER: [RegexHandler('^(Boy|Girl|Other)$', gender)],

        PHOTO: [MessageHandler([Filters.photo], photo),
                CommandHandler('skip', skip_photo)],

        LOCATION: [MessageHandler([Filters.location], location),
                   CommandHandler('skip', skip_location)],

        BIO: [MessageHandler([Filters.text], bio)]
    },

    fallbacks=[CommandHandler('cancel', cancel)]
)

TODO

• @run_async integration
• Tests