Hubot-Conversation

Have a multi-message chat with your bot.

#####Reminder, before you start: This does not need to be added to external-scripts. ##How it works:

1. Make a new Conversation instance aware of your robot:

   var switchBoard = new Conversation(robot, [type]);

This will register a custom listener allowing the instance to check all incoming messages. Type parameter can take one of two values: user (default) or room. It defines if this conversation is with the whole room or with a particular user only. If the message comes from a user (or a room) that we're having a conversation with, it will be processed as the next step in an ongoing Dialog.

2. Given an starting message, create a new Dialog instance and give the dialog choices.

robot.hear(/delete all the files/, function(msg) {

    msg.reply('Are you really sure???');
    
    //Start a dialog with the user that sent this message.
    var dialog = switchBoard.startDialog(msg);
    
    //Provide choices for the next step, wait for the user.
    dialog.addChoice(/yes/, function(msg2){/*Do some stuff for the yes option*/}
    dialog.addChoice( /no/, function(msg2){/*Do some stuff for the no option*/ }

    //The dialog will expire after 30 secods.  
});

The switchBoard will listen to the next message from the same user (or room) and try to match it to any of the available choices. After a match has been found. It will clear the choices, and end the dialog.

The bot will forget about your dialog after a default timeout of 30 seconds.

##Use

On your hubot script:

var Conversation = require('hubot-conversation');
module.exports = function (robot) {

    var switchBoard = new Conversation(robot);

    robot.respond(/clean the house/, function (msg) {
        var dialog = switchBoard.startDialog(msg);

        msg.reply('Sure, where should I start? Kitchen or Bathroom');
        dialog.addChoice(/kitchen/i, function (msg2) {
            msg2.reply('On it boss!');
        });
        dialog.addChoice(/bathroom/i, function (msg2) {
            msg.reply('Do I really have to?');
            dialog.addChoice(/yes/, function (msg3) {
                msg3.reply('Fine, Mom!');
            })
        });
    });

    robot.respond(/jump/, function (msg) {
        var dialog = switchBoard.startDialog(msg);
        msg.reply('Sure, How many times?');
        
        dialog.addChoice(/([0-9]+)/i, function (msg2) {
            var times = parseInt(msg2.match[1], 10);
            for (var i = 0; i < times; i++) {
                msg.emote("Jumps"); //We can use the original message too.
            }
        });
    });
    
    
  robot.respond(/.*the mission/, function (msg) {
        msg.reply('You have 5 seconds to accept your mission, or this message will self-destruct');
        var dialog = switchBoard.startDialog(msg, 5000); //5 Second timeout
        dialog.dialogTimeout = function (msg2) {
            msg2.emote('Boom');
        }
        dialog.addChoice(/yes/i, function (msg2) {
            msg2.reply('Great! Here are the details...');
        });
    });
};

This will give you the following interactions:

hubot> hubot clean the house
hubot> Shell: Sure, where should I start? Kitchen or Bathroom
hubot> Kitchen
hubot> Shell: On it boss!
hubot> hubot clean the house
hubot> Shell: Sure, where should I start? Kitchen or Bathroom
hubot> Bathroom
hubot> Shell: Do I really have to?
hubot> yes
hubot> Shell: Fine, Mom!

hubot> hubot jump
hubot> Shell: Sure, How many times?
hubot> 3
hubot> ready to jump 3 3
* Jumps
* Jumps
* Jumps

hubot> hubot what's the mission?
hubot> Shell: You have 5 seconds to accept your mission, or this message will self-destruct
//5 seconds later
* Boom  

##API

###Conversation

startDialog(msg, [timeout], [timeoutMessage])

Returns a new Dialog object, with a default timeout of 30000ms.

msg: An incoming message heard / responded to by the robot eg:

robot.respond(/foo/,function(msg){ 
   var dialog = conversation.startDialog(msg);
})

timeout: optional time in ms before the conversaion expires. The Dialog object has a default timeout function property which can be overriden to specify the timeout behavior

timeoutMessage: optional message to send when when the conversation expires. The Dialog object has a default timeout function property which can be overriden to specify the timeout behavior

talkingTo(id)

Returns the Dialog being held with a given user

id: The Id of the user with whom a dialog is taking place.

Dialog

A multiple-choice message handler

receive(msg)

Process an incoming message to see if any choice matches it.

msg A hubot message

addChoice(regex, handler)

Adds a listener choice to this Dialog. This works just like hubots hear listener. If a message is received that matches the choice regex, the handler will be executed.

regex a regular expresion that will be aplied to the incoming message from the receive function handler: function(message), A function that is executed against a successfully matched message. The match property of the original message is replaced by the match against this regex, so you can retrieve matched groups.

getChoices()

Returns the array of choices

resetChoices()

Clears the choices.

dialogTimeout -> function(message){ }

Default timeout handler. You can override this property with your own function.