yowl-dialog-manager
v0.7.3
Published
Multi-interaction dialog management for yowl
Downloads
14
Readme
yowl-dialog-manager
Multi-interaction dialog management for yowl
Install
$ npm install yowl-dialog-manager --save
Dialog Manager requires a persistent yowl session to handle dialog chaining and responses. IF YOU DO NOT USE ONE OF THESE, YOUR DIALOG MANAGERS WILL NOT WORK.
yowl-session-memory
yowl-session-redis
yowl-session-rethink
Example
var yowl = require('yowl');
var bot = yowl();
bot.name = "Dialog Bot";
var local = require('yowl-platform-cli');
bot.extend(local);
var memory = require('yowl-context-memory');
bot.use(memory);
var DialogManager = require('yowl-dialog-manager')();
DialogManager.add('greet', {
test: function(context, event) {
return !context.session.greeted;
},
messages: [
"Hello there!",
"This an example of a multi-step dialog.",
"As a note, chaining dialogs between multiple interactions requires a persisted context.",
"This dialog is an overly complicated echo example."
],
after: function(context, event, callback) {
context.session.greeted = true;
this.manager.dialogs.step_1.play(context, event, callback);
}
});
DialogManager.add('step_1', {
messages: [
"What is the message that you'd like me to echo back?"
],
onresponse: function(context, event, callback) {
context.session.echo = event.message;
this.manager.dialogs.step_2.play(context, event, callback);
}
});
DialogManager.add('step_2', {
messages: [
"You told me to echo \"{echo}\""
],
after: function(context, event, callback) {
delete context.session.echo;
this.manager.dialogs.step_1.play(context, event, callback);
}
});
bot.use(DialogManager);
bot.run();
Install all dependencies.
$ npm install --save yowl yowl-platform-cli yowl-dialog-manager yowl-context-memory
Then run your bot.
node bot.js --local
Usage
yowl-dialog-manager
exports a Manager
class that can be instantiated and then added to a bot with bot.use()
var yowl = require('yowl');
var bot = yowl();
var Manager = require('yowl-dialog-manager');
var myManager = Manager('namespace', { preserve_on_error: false });
bot.use(myManager);
The Manager
has the following positional arguments:
namespace
(String, optional) - a unique namespace for this manager, required if you are using managers which have dialogs with clashing ids. You probably want to setup a namespace regardless.options
(Object, optional) - an options object. currently, the only option ispreserve_on_error
(Boolean, default false) which, when set to true, will preserve the current dialog chain in the event of an uncaught error. You most likely want to leave this to false so that your users don't get stuck in a continous error loop.
Dialogs are added to the manager using Manager.add(dialog_id, dialog_object)
Dialogs have the following options.
messages
(Array or Function(context, event, callback), Optional) - If array, a list of strings to send to the user. If function, a function that returns an array of strings to send to the user. Strings are automatically interpolated using values from the localcontext.session
. So if yourcontext.session
is{ name: "Goose" }
and your string isHello there {name}!
, the user will be sentHello there Goose!
. Variable names for interpolation can include multiple levels of properties (e.g.{user.name}
)actions
(Array, Optional) - A list of actions to be sent back to the user. For more information on how actions work, you visis the capabilities documentation.test
(Boolean or Function(context, event, callback), Optional, Defaultfalse
) - This determines whether or not a dialog should be run. If this is a boolean,true
will always cause the dialog to run andfalse
will cause it to never run. If it's a function, the function should resemblefunction(context, event) { ... some code ... }
and should return a boolean.onresponse
(Function(context, event, callback), optional) - A function to run when the user responds to a dialog. When a dialog withonresponse
defined is run, the manager will automatically ensure that theonresponse
function is running when the user sends a new interaction. It must call callback.before
(Function(context, event, callback), Optional) - A function to run before sendingmessages
. It must call callback.after
(Function(context, event, callback), Optional) - A function to run after sendingmessages
. It must call callback.cascade
(boolean, defaultfalse
) - Whether or not to continue on to further methods in the bot
For onresponse
, before
and after
(and messages
if you are supplying a function), you may omit the third argument callback
if you do not need to do any asynchronous processing.
Chaining Dialogs
You'll often want to call another dialog from the after
or onresponse
functions. This can be done by calling a dialog's play
function. By default, all dialogs are available by their id on their associated manager's dialogs
property.
DialogManager.add('step_1', {
messages: [
"When you respond, I'll call another dialog!!!"
],
onresponse: function(context, event, callback) {
context.user_message = event.message;
this.manager.dialogs.step_2.play(context, event, callback);
}
});
DialogManager.add('step_2', {
messages: [
"Here's the other dialog!!!",
"You said {user_message}.",
"Now we start all over again."
],
after: function(context, event, callback) {
delete context.user_message;
this.manager.dialogs.step_1.play(context, event, callback);
}
});
Organization
You can structure your project so you have multiple dialog managers in seperate files, and then include them all.
var onboardingDialogs = require('./dialogs/onboarding');
var settingsDialogs = require('./dialogs/settings');
var interactionDialogs = require('./dialogs/interactions');
bot.use(onboardingDialogs);
bot.use(settingsDialogs);
bot.use(interactionDialogs);