python-telegram-bot · jh0ker · Jul 14, 2016 · Jun 23, 2016 · Jun 23, 2016 · Jun 24, 2016
diff --git a/docs/source/telegram.ext.callbackqueryhandler.rst b/docs/source/telegram.ext.callbackqueryhandler.rst
@@ -1,7 +1,7 @@
-telegram.ext.handler module
-===========================
+telegram.ext.callbackqueryhandler module
+========================================
 
-.. automodule:: telegram.ext.handler
+.. automodule:: telegram.ext.callbackqueryhandler
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/source/telegram.ext.conversationhandler.rst b/docs/source/telegram.ext.conversationhandler.rst
@@ -0,0 +1,7 @@
+telegram.ext.conversationhandler module
+=======================================
+
+.. automodule:: telegram.ext.conversationhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst
@@ -11,6 +11,7 @@ Submodules
     telegram.ext.jobqueue
     telegram.ext.handler
     telegram.ext.choseninlineresulthandler
+    telegram.ext.conversationhandler
     telegram.ext.commandhandler
     telegram.ext.inlinequeryhandler
     telegram.ext.messagehandler

diff --git a/examples/conversationbot.py b/examples/conversationbot.py
@@ -0,0 +1,160 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few callback functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Example of a bot-user conversation using ConversationHandler.
+Send /start to initiate the conversation.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import (ReplyKeyboardMarkup)
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
+                          ConversationHandler)
+
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+GENDER, PHOTO, LOCATION, BIO = range(4)
+
+
+def start(bot, update):
+    reply_keyboard = [['Boy', 'Girl', 'Other']]
+
+    bot.sendMessage(update.message.chat_id,
+                    text='Hi! My name is Professor Bot. I will hold a conversation with you. '
+                         'Send /cancel to stop talking to me.\n\n'
+                         'Are you a boy or a girl?',
+                    reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True))
+
+    return GENDER
+
+
+def gender(bot, update):
+    user = update.message.from_user
+    logger.info("Gender of %s: %s" % (user.first_name, update.message.text))
+    bot.sendMessage(update.message.chat_id,
+                    text='I see! Please send me a photo of yourself, '
+                         'so I know what you look like, or send /skip if you don\'t want to.')
+
+    return PHOTO
+
+
+def photo(bot, update):
+    user = update.message.from_user
+    photo_file = bot.getFile(update.message.photo[-1].file_id)
+    photo_file.download('user_photo.jpg')
+    logger.info("Photo of %s: %s" % (user.first_name, 'user_photo.jpg'))
+    bot.sendMessage(update.message.chat_id, text='Gorgeous! Now, send me your location please, '
+                                                 'or send /skip if you don\'t want to.')
+
+    return LOCATION
+
+
+def skip_photo(bot, update):
+    user = update.message.from_user
+    logger.info("User %s did not send a photo." % user.first_name)
+    bot.sendMessage(update.message.chat_id, text='I bet you look great! Now, send me your '
+                                                 'location please, or send /skip.')
+
+    return LOCATION
+
+
+def location(bot, update):
+    user = update.message.from_user
+    user_location = update.message.location
+    logger.info("Location of %s: %f / %f"
+                % (user.first_name, user_location.latitude, user_location.longitude))
+    bot.sendMessage(update.message.chat_id, text='Maybe I can visit you sometime! '
+                                                 'At last, tell me something about yourself.')
+
+    return BIO
+
+
+def skip_location(bot, update):
+    user = update.message.from_user
+    logger.info("User %s did not send a location." % user.first_name)
+    bot.sendMessage(update.message.chat_id, text='You seem a bit paranoid! '
+                                                 'At last, tell me something about yourself.')
+
+    return BIO
+
+
+def bio(bot, update):
+    user = update.message.from_user
+    logger.info("Bio of %s: %s" % (user.first_name, update.message.text))
+    bot.sendMessage(update.message.chat_id,
+                    text='Thank you! I hope we can talk again some day.')
+
+    return ConversationHandler.END
+
+
+def cancel(bot, update):
+    user = update.message.from_user
+    logger.info("User %s canceled the conversation." % user.first_name)
+    bot.sendMessage(update.message.chat_id,
+                    text='Bye! I hope we can talk again some day.')
+
+    return ConversationHandler.END
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
+    conv_handler = 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)]
+    )
+
+    dp.add_handler(conv_handler)
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/telegram/ext/__init__.py b/telegram/ext/__init__.py
@@ -31,8 +31,9 @@
 from .stringcommandhandler import StringCommandHandler
 from .stringregexhandler import StringRegexHandler
 from .typehandler import TypeHandler
+from .conversationhandler import ConversationHandler
 
 __all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
            'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler',
            'MessageHandler', 'Filters', 'RegexHandler', 'StringCommandHandler',
-           'StringRegexHandler', 'TypeHandler')
+           'StringRegexHandler', 'TypeHandler', 'ConversationHandler')
diff --git a/telegram/ext/callbackqueryhandler.py b/telegram/ext/callbackqueryhandler.py
@@ -52,7 +52,7 @@ def check_update(self, update):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.CallbackQueryHandler."

diff --git a/telegram/ext/choseninlineresulthandler.py b/telegram/ext/choseninlineresulthandler.py
@@ -53,7 +53,7 @@ def check_update(self, update):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.ChosenInlineResultHandler."

diff --git a/telegram/ext/commandhandler.py b/telegram/ext/commandhandler.py
@@ -83,7 +83,7 @@ def handle_update(self, update, dispatcher):
         if self.pass_args:
             optional_args['args'] = message.text.split(' ')[1:]
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.CommandHandler."