botmaster-humanise-ware v2.0.3

Humanise Middleware for Botmaster

This middleware allows you to easily connect an external bot to the Humanise.AI platform. It does so by sending every incoming and outgoing update (for now, only those that contains text) to the humanise platform.

It is written as a wrapped middleware (see here) for more on botmaster middleware.

Incoming updates

Incoming updates would come from a certain platform (i.e. FB messenger) and this middleware would just forward the update to the humanise platform.

Outgoing Updates

Because we want to be able to leverage the humanise platform, we want to be able to both supervise and pause the bot we have written. To do that, instead of sending outgoing updates straight back to the platform, we send it to humanise. We then setup a local endpoint humanise then calls back in order to let us know if/when to send an update object. Humanise can also use this endpoint to send human agent updates straight to a wanted platform. Read more about this in the following 2 sections (Usage and Examples)

As this library uses async/await please use Node.JS 8 or greater

Usage

Once you have received your ApiKey and botUserId from humanise, you will need to setup a project. Here is a minimal example of such a setup. This example uses express. But using any other webserver should work (our Watson Conversation example uses koa)

const express = require('express')
const bodyParser = require('body-parser')
const Botmaster = require('botmaster')
const MessengerBot = require('botmaster-messenger') // for this example
const { makeHumaniseWare } = require('botmaster-humanise-ware')


// 1) create http server from express app object that will be used later
const PORT = 3000
const app = express();
const server = app.listen(PORT, '0.0.0.0');

// 2) create botmaster object and mount middleware
const HUMANISE_API_KEY = 'Your_HUMANISE_API_KEY'
// this url will be created by humanise and displayed in the UI upon creation of a custom channel
const HUMANISE_INCOMING_WEBHOOK_URL='YOUR_HUMANISE_INCOMING_WEBHOOK_URL'

const botmaster = new Botmaster({ server })

// enter your messenger credentials. You can also use another bot class if
// your bot supports other platforms. Have a look at the `botmaster-messenger` project for more info on that: https://github.com/botmasterai/botmaster-messenger
botmaster.addBot(new MessengerBot({
  credentials: {
    verifyToken: 'Your VERIFY_TOKEN',
    pageToken: 'Your PAGE_TOKEN',
    fbAppSecret: 'Your FB_APP_SECRET'
  },
  webhookEndpoint: 'Your WEBHOOK_ENDPOINT'
}))

// simple incoming middleware that replies randomly from a set of deterministic replies
botmaster.use({
  type: 'incoming',
  name: 'send-reply-to-user',
  controller: async (bot, update) => {
    const = replies [
      'hi there',
      'I hope you are having a good day',
      'my name is botmaster-bot',
      '<handoff>reason</handoff>'
    ]

    const randomReply = replies[Math.floor(Math.random() * replies.length)];

    return bot.sendTextMessageTo(randomReply, update.sender.id)
  }
})

.
.
.

// after adding all your other middleware and wrapped middleware (a potential logging wrapped middleware can still come after)

const humaniseWare = makeHumaniseWare({
  apiKey: HUMANISE_API_KEY,
  incomginWebhookUrl: HUMANISE_INCOMING_WEBHOOK_URL
})

botmaster.useWrapped(humaniseWare.incoming, humaniseWare.outgoing)

// 3) make sure your express web-server has a /humanise endpoint it can
// receive requests from humanise on.

// just bodyParser stuff
app.use(bodyParser.urlencoded({ extended: false }))
// parse application/json
app.use(bodyParser.json())

app.post('/humanise', (req, res) => {
  const receivedBody = req.body
  // We take out the "messenger" platform bot object, but humanise specifies this in its
  // request and we could actually extract it if we wanted to do this dynamically
  const bot = botmaster.getBot({ type: 'messenger' })
  // use await to make sure humanise sends the following messages only once the
  // end platform has received the previous message
  try {
    await bot.sendMessage(receivedBody)
    logger.debug(`sent message to ${receivedBody.message.recipient}`)
  } catch (err) {
    logger.error(err)
  } finally {
    // still returning ok, because want to go to the next message
    res.send = 'Ok'
  }
})

Examples

For an example that actually does something useful, have a look at the Facebook Messenger example.

• Watson on Facebook Messenger

API

Table of Contents

• makeHumaniseWare

makeHumaniseWare

Make botmaster middleware

Parameters

• $0 Object
  • $0.apiKey
  • $0.botUserId
  • $0.logger
  • $0.getEscalationFromUpdate
• ApiKey $0.apiKey Humanise.AI API Key
• botUserId $0.apiKey Humanise.API Bot ID to register updates as.
• Logger $0.logger? optional logger with .verbose, .debug, .error, .info, .warning methods
• getEscalationFromUpdate $0.getEscalationFromUpdate? optional async function that takes a botmaster update and returns 'lowSentiment', 'handoff', 'lowConfidence' or null. Use this param to dynamically set whether you want to escalade a conversation based on a certain user input message. Sentiment of the user's message is a good example of how to use this.