Add rasa project, better documentation, add example

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 .vscode
+.DS_Store
+npm-debug.log

.npmignore

@@ -0,0 +1,6 @@
+example
+node_modules
+.vscode/*
+.gitignore
+.DS_Store
+npm-debug.log

LICENSE

@@ -0,0 +1,17 @@
+ISC License (ISC)
+
+Copyright (c) 2017, Alessio "LeX" Calafiore
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyright notice and this permission notice appear
+in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -0,0 +1,74 @@
+# Botkit / Rasa NLU plugin
+
+This plugin provides Botkit developers a way to use the [Rasa NLU](https://rasa.ai/) open source, self hosted natural language API.
+
+## Setup in your project
+
+Install the plugin using the npm package
+
+`npm i --save botkit-rasa`
+
+Make your bot aware of the plugin:
+```
+var rasa = require('botkit-rasa')({rasa_uri: 'http://localhost:5000'});
+controller.middleware.receive.use(rasa.receive);
+
+controller.hears(['my_intent'],'message_received', rasa.hears, function(bot, message) {
+
+    console.log('Intent:', message.intent);
+    console.log('Entities:', message.entities);    
+
+});
+```
+
+## Example Slack bot
+In the `example` directory there's a fully functional Slack bot sample.
+
+This bot demonstrates some core features of Botkit
+leveraging Rasa NLU plugin:
+* Connect to Slack using the real time API
+* Receive messages based on "spoken" patterns
+* Reply to messages
+
+### Prerequisites
+* Install [Node.js](https://nodejs.org/)
+
+### Run the example bot
+Get Rasa NLU up and running by checking out [their repository](https://github.com/RasaHQ/rasa_nlu) and following the [instructions to setup](https://github.com/RasaHQ/rasa_nlu#setup) a Rasa NLU instance.
+At this point you should have a Rasa NLU instance up and running.
+
+Now get a Bot token from Slack (you will need this later when launching the bot from the command line):
+* http://my.slack.com/services/new/bot
+
+Clone this repository and move into the example directory:
+* `git clone https://github.com/sohlex/botkit-rasa.git`
+
+Open another terminal and from the example directory, run the commands (`TOKEN` is the one that you got before from the slack website):
+* `npm install`
+* `slack_token=<TOKEN> node bot.js`
+
+### Use the bot
+Find your bot inside Slack to send it a direct message.
+
+Say: "Hello"
+
+The bot should reply "Hello!" If it didn't, there's a problem with
+Rasa NLU configuration, check the bot and Rasa console for errors.
+
+Make sure to invite your bot into other channels using /invite @<my bot>!
+
+### Extend the bot
+
+If this middleware doesn't satisfy your needs, you can use it as inspiration for your implementations or contribute to this project!
+Furthermore, Botkit has many features for building cool and useful bots!
+
+Read all about it [here](http://howdy.ai/botkit).
+
+## What this middleware does
+Using this Rasa NLU middleware plugin for Botkit causes every message that is sent to your bot to be first sent to Rasa NLU for processing. The results of the call to Rasa NLU are added into the incoming message as `message.intents` and `message.entities`.
+
+Using the Rasa NLU `hears` middleware tells Botkit to look for Rasa NLU intents information, and match them using this information instead of the built in pattern matching function.
+
+You must create an intent in the understandings area of Rasa NLU and train it to register certain expressions.
+
+More informations are available in the [Rasa NLU documentation](https://rasa-nlu.readthedocs.io/en/latest/)

example/bot.js

@@ -0,0 +1,85 @@
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+           ______     ______     ______   __  __     __     ______
+          /\  == \   /\  __ \   /\__  _\ /\ \/ /    /\ \   /\__  _\
+          \ \  __<   \ \ \/\ \  \/_/\ \/ \ \  _"-.  \ \ \  \/_/\ \/
+           \ \_____\  \ \_____\    \ \_\  \ \_\ \_\  \ \_\    \ \_\
+            \/_____/   \/_____/     \/_/   \/_/\/_/   \/_/     \/_/
+
+This is a sample Slack bot built with Botkit.
+
+This bot demonstrates some core features of Botkit
+leveraging Rasa NLU plugin:
+
+* Connect to Slack using the real time API
+* Receive messages based on "spoken" patterns
+* Reply to messages
+
+# RUN THE BOT:
+
+  Get Rasa NLU up and running by checking out their repository
+
+    -> https://github.com/RasaHQ/rasa_nlu
+
+  Follow the instructions on the README.md file and start Rasa NLU
+
+  Then get a Bot token from Slack:
+
+    -> http://my.slack.com/services/new/bot
+
+  Clone the botkit-rasa repository and move into the example directory:
+
+    -> git clone https://github.com/sohlex/botkit-rasa.git
+
+  Open the terminal and from the example directory, run the commands:
+
+    -> npm install
+    -> slack_token= <token> node bot.js
+
+# USE THE BOT:
+
+  Find your bot inside Slack to send it a direct message.
+
+  Say: "Hello"
+
+  The bot should reply "Hello!" If it didn't, there's a problem with
+  Rasa NLU configuration, check the bot and Rasa console for errors.
+
+  Make sure to invite your bot into other channels using /invite @<my bot>!
+
+# EXTEND THE BOT:
+
+  Botkit is has many features for building cool and useful bots!
+
+  Read all about it here:
+
+    -> http://howdy.ai/botkit
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+
+if (!process.env.slack_token) {
+  console.log('Error: Specify token in environment')
+  process.exit(1)
+}
+
+const Botkit = require('botkit')
+const rasa = require('../src/middleware-rasa')({
+  rasa_uri: 'http://localhost:5000',
+  rasa_project: undefined
+})
+
+const controller = Botkit.slackbot({
+  debug: true
+})
+
+const bot = controller.spawn({
+  token: process.env.slack_token
+}).startRTM()
+console.log(rasa)
+controller.middleware.receive.use(rasa.receive)
+
+/* this uses rasa middleware defined above */
+controller.hears(['greet'], 'direct_message,direct_mention,mention', rasa.hears, function (bot, message) {
+  console.log(JSON.stringify(message))
+  console.log('hello')
+  bot.reply(message, 'Hello!')
+})

example/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "bot.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "botkit": "^0.5.4",
+    "botkit-rasa": "^1.0.6"
+  }
+}

index.js

@@ -0,0 +1 @@
+module.exports = require('./src/middleware-rasa')

package.json

@@ -1,13 +1,36 @@
 {
   "name": "botkit-rasa",
-  "version": "1.0.0",
+  "version": "1.0.7",
   "description": "",
-  "main": "src/middleware.js",
+  "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "author": "ben@howdy.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sohlex/botkit-rasa.git"
+  },
+  "keywords": [
+    "botkit",
+    "rasa",
+    "rasa nlu",
+    "rasanlu",
+    "bot",
+    "bots",
+    "slack",
+    "messenger"
+  ],
+  "author": "Alessio Calafiore <alessio.calafiore@gmail.com>",
+  "contributors": [
+    { "name" : "Ben",
+      "email" : "ben@howdy.ai"
+    }
+  ],
   "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/sohlex/botkit-rasa/issues"
+  },
+  "homepage": "https://github.com/sohlex/botkit-rasa#readme",
   "dependencies": {
     "debug": "^2.6.8",
     "request": "^2.81.0",

readme.md

@@ -1,8 +1,14 @@
-# Botkit / rasa NLU plugin
+# Botkit / Rasa NLU plugin
 
-This plugin provides Botkit developers a way to use the [rasa NLU](https://rasa.ai/) open source, self hosted natural language API.
+This plugin provides Botkit developers a way to use the [Rasa NLU](https://rasa.ai/) open source, self hosted natural language API.
 
+## Setup in your project
 
+Install the plugin using the npm package
+
+`npm i --save botkit-rasa`
+
+Make your bot aware of the plugin:
 ```
 var rasa = require('botkit-rasa')({rasa_uri: 'http://localhost:5000'});
 controller.middleware.receive.use(rasa.receive);
@@ -14,3 +20,55 @@ controller.hears(['my_intent'],'message_received', rasa.hears, function(bot, mes
 
 });
 ```
+
+## Example Slack bot
+In the `example` directory there's a fully functional Slack bot sample.
+
+This bot demonstrates some core features of Botkit
+leveraging Rasa NLU plugin:
+* Connect to Slack using the real time API
+* Receive messages based on "spoken" patterns
+* Reply to messages
+
+### Prerequisites
+* Install [Node.js](https://nodejs.org/)
+
+### Run the example bot
+Get Rasa NLU up and running by checking out [their repository](https://github.com/RasaHQ/rasa_nlu) and following the [instructions to setup](https://github.com/RasaHQ/rasa_nlu#setup) a Rasa NLU instance.
+At this point you should have a Rasa NLU instance up and running.
+
+Now get a Bot token from Slack (you will need this later when launching the bot from the command line):
+* http://my.slack.com/services/new/bot
+
+Clone this repository and move into the example directory:
+* `git clone https://github.com/sohlex/botkit-rasa.git`
+
+Open another terminal and from the example directory, run the commands (`TOKEN` is the one that you got before from the slack website):
+* `npm install`
+* `slack_token=<TOKEN> node bot.js`
+
+### Use the bot
+Find your bot inside Slack to send it a direct message.
+
+Say: "Hello"
+
+The bot should reply "Hello!" If it didn't, there's a problem with
+Rasa NLU configuration, check the bot and Rasa console for errors.
+
+Make sure to invite your bot into other channels using /invite @<my bot>!
+
+### Extend the bot
+
+If this middleware doesn't satisfy your needs, you can use it as inspiration for your implementations or contribute to this project!
+Furthermore, Botkit has many features for building cool and useful bots!
+
+Read all about it [here](http://howdy.ai/botkit).
+
+## What this middleware does
+Using this Rasa NLU middleware plugin for Botkit causes every message that is sent to your bot to be first sent to Rasa NLU for processing. The results of the call to Rasa NLU are added into the incoming message as `message.intents` and `message.entities`.
+
+Using the Rasa NLU `hears` middleware tells Botkit to look for Rasa NLU intents information, and match them using this information instead of the built in pattern matching function.
+
+You must create an intent in the understandings area of Rasa NLU and train it to register certain expressions.
+
+More informations are available in the [Rasa NLU documentation](https://rasa-nlu.readthedocs.io/en/latest/)

src/middleware.js → src/middleware-rasa.js

@@ -12,7 +12,10 @@ module.exports = config => {
 
   var middleware = {
     receive: (bot, message, next) => {
-      if (!message.text || message.is_echo) {
+      // is_echo: can be true for facebook bots when the echo webhook is subscribed
+      // bot_id: keep an eye https://github.com/howdyai/botkit/pull/694
+      // if bot_id is present, the message comes from another bot
+      if (!message.text || message.is_echo || message.bot_id) {
         next()
         return
       }
@@ -22,7 +25,8 @@ module.exports = config => {
         method: 'POST',
         uri: `${config.rasa_uri}/parse`,
         body: {
-          q: message.text
+          q: message.text,
+          project: `${config.rasa_project}`
         },
         json: true
       }