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:

``javascript
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.

`javascript
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:

`javascript

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('Your have 5 seconds to accept your mission, or this message will self-destruct');
var dialog = switchBoard.startDialog(msg, 5000); //5 Second timeout
dialog.timeout = 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:

`bash
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!

`

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

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


##API

###Conversation

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

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

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

`javascript
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

##### talkingTo(id)

Returns the Dialog being held with a given user

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




$3


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.