chore: merge changes from master

Author: germanattanasio

README.md

@@ -152,6 +152,36 @@ var receiveMiddleware = function (bot, message, next) {
 slackController.middleware.receive.use(receiveMiddleware);
 ```
 
+### Minimum Confidence
+
+To use the setup parameter `minimum_confidence`, you have multiple options:
+
+#### Use it manually in your self-defined controller.hears() function(s)
+
+For example:
+```js
+controller.hears(['.*'], ['direct_message', 'direct_mention', 'mention', 'message_received'], function(bot, message) {
+  if (message.watsonError) {
+    bot.reply(message, "Sorry, there are technical problems.");     // deal with watson error
+  } else {
+    if (message.watsonData.intents.length == 0) {
+      bot.reply(message, "Sorry, I could not understand the message.");     // was any intent recognized?
+    } else if (message.watsonData.intents[0].confidence < watsonMiddleware.minimum_confidence) {
+      bot.reply(message, "Sorry, I am not sure what you have said.");      // is the confidence high enough?
+    } else {
+      bot.reply(message, message.watsonData.output.text.join('\n'));      // reply with Watson response
+    }
+  }
+});
+```
+
+#### Use the middleware's hear() function
+You can find the default implementation of this function [here](https://github.com/watson-developer-cloud/botkit-middleware/blob/e29b002f2a004f6df57ddf240a3fdf8cb28f95d0/lib/middleware/index.js#L40). If you want, you can redefine this function in the same way that watsonMiddleware.before and watsonMiddleware.after can be redefined. Refer to the [Botkit Middleware documentation](https://github.com/howdyai/botkit/blob/master/docs/middleware.md#hear-middleware) for an example. Then, to use this function instead of Botkit's default pattern matcher (that does not use minimum_confidence), plug it in using:
+```js
+controller.changeEars(watsonMiddleware.hear)
+```
+
+Note: if you want your own `hear()` function to implement pattern matching like Botkit's default one, you will likely need to implement that yourself. Botkit's default set of 'ears' is the `hears_regexp` function which is implemented [here](https://github.com/howdyai/botkit/blob/77b7d7f80c46d5c8194453667d22118b7850e252/lib/CoreBot.js#L1180).
 
 ### Implementing app actions
 

examples/multi-bot/bot-facebook.js

@@ -23,7 +23,15 @@ var controller = Botkit.facebookbot({
 
 var bot = controller.spawn();
 controller.hears('(.*)', 'message_received', function(bot, message) {
-  bot.reply(message, message.watsonData.output.text.join('\n'));
+  if (message.watsonError) {
+    console.log(message.watsonError);
+    bot.reply(message, message.watsonError.description || message.watsonError.error);
+  } else if (message.watsonData && 'output' in message.watsonData) {
+    bot.reply(message, message.watsonData.output.text.join('\n'));
+  } else {
+    console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
+    bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
+  }
 });
 
 module.exports.controller = controller;

examples/multi-bot/bot-slack.js

@@ -22,7 +22,15 @@ var bot = controller.spawn({
 });
 
 controller.hears(['.*'], ['direct_message', 'direct_mention', 'mention'], function(bot, message) {
-  bot.reply(message, message.watsonData.output.text.join('\n'));
+  if (message.watsonError) {
+    console.log(message.watsonError);
+    bot.reply(message, message.watsonError.description || message.watsonError.error);
+  } else if (message.watsonData && 'output' in message.watsonData) {
+    bot.reply(message, message.watsonData.output.text.join('\n'));
+  } else {
+    console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
+    bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
+  }
 });
 
 module.exports.controller = controller;

examples/multi-bot/bot-twilio.js

@@ -27,7 +27,15 @@ var bot = controller.spawn({
   autojoin: true
 });
 controller.hears(['.*'], 'message_received', function(bot, message) {
-  bot.reply(message, message.watsonData.output.text.join('\n'));
+  if (message.watsonError) {
+    console.log(message.watsonError);
+    bot.reply(message, message.watsonError.description || message.watsonError.error);
+  } else if (message.watsonData && 'output' in message.watsonData) {
+    bot.reply(message, message.watsonData.output.text.join('\n'));
+  } else {
+    console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
+    bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
+  }
 });
 
 module.exports.controller = controller;

examples/simple-bot/simple-bot-slack.js

@@ -36,9 +36,12 @@ slackController.hears(['.*'], ['direct_message', 'direct_mention', 'mention'], f
   middleware.interpret(bot, message, function() {
     if (message.watsonError) {
       console.log(message.watsonError);
-      bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
-    } else {
+      bot.reply(message, message.watsonError.description || message.watsonError.error);
+    } else if (message.watsonData && 'output' in message.watsonData) {
       bot.reply(message, message.watsonData.output.text.join('\n'));
+    } else {
+      console.log('Error: received message in unknown format. (Is your connection with Watson Conversation up and running?)');
+      bot.reply(message, 'I\'m sorry, but for technical reasons I can\'t respond to your message');
     }
   });
 });