Wordhop monitors your Chatbot and alerts you on Slack in real-time when it detects conversational problems. You can watch your bot conversations with users in real-time without leaving Slack and take-over your bot to engage your customers directly. Simply add Wordhop to Slack and then drop in code into your Chatbot (You can use our examples as a starting point for a bot too). Wordhop integrates in minutes, and begins working immediately.

This module has been tested with Messenger, Slack, Skype, and Microsoft Webchat. Please see our examples.

• See Key Features
• Watch a Demo

• A Slack Account
• Wordhop for Slack
• A Chatbot built in Node.js

1. You'll need an API key from Wordhop and for each Chatbot a Bot Token. You can get both of those (free) when you add Wordhop to Slack and through a conversation with Wordhop.
2. If you're building a Messenger Chatbot, you'll need to setup a Facebook App, Facebook Page, get the Page Access Token from Facebook and link the Facebook App to the Facebook Page for Wordhop to work.

$ npm install --save wordhop

var Wordhop = require('wordhop');
var apiKey = process.env.WORDHOP_API_KEY; // <= key provided by Wordhop for Slack
var clientKey = process.env.WORDHOP_CLIENT_KEY; // <= key provided by Wordhop for Slack
var botPlatform = 'messenger'; // <= possible values: 'messenger', 'slack'
var token = process.env.PAGE_ACCESS_TOKEN; // <= only required for Messenger bots.
var wordhop = Wordhop(apiKey, clientKey, {platform: botPlatform, token:token});

Throughout this documentation, you will see references to incomingMessage. Depending on whether you have a Messenger or Slack bot, the schema will be different. The value of incomingMessage should be equal to the message you receive directly from either the Messenger webhook response, or from the Slack RTM event response.

// Example of a Slack Incoming Message
{
    "type": "message",
    "channel": "D024BE91L",
    "user": "U2147483697",
    "text": "Hello world",
    "ts": "1355517523.000005"
}

// Example of a Messenger Incoming Message
{
  "sender":{
    "id":"USER_ID"
  },
  "recipient":{
    "id":"PAGE_ID"
  },
  "timestamp":1458692752478,
  "message":{
    "mid":"mid.1457764197618:41d102a3e1ae206a38",
    "seq":73,
    "text":"hello, world!",
    "quick_reply": {
      "payload": "DEVELOPER_DEFINED_PAYLOAD"
    }
  }
}  

Throughout this documentation, you will see references to outgoingMessage. Depending on whether you have a Messenger or Slack bot, the schema, as defined by each platform, will be different. Every time you track an outgoing message, the schema requirements match the respective platform.

// Example of Slack Outgoing Message
{
    "channel": "C024BE91L",
    "text": "Hello world"
}

// Exmaple of Messenger Outgoing Message
{
  "recipient":{
    "id":"USER_ID"
  },
  "message":{
    "text":"hello, world!"
  }
}

When your bot receives an incoming message, you'll need to log the data with Wordhop by calling to wordhop.hopIn. Note: Wordhop can pause your bot so that it doesn't auto response while a human has taken over. The callback from your hopIn request will pass the isBotPaused Bool value. If true, use that to stop your bot from responding to an incoming message. Here is an example:

// Let Wordhop know when a message comes in 
wordhop.hopIn(incomingMessage, function(isBotPaused) {
    // If your bot is paused, stop it from replying
    if (isBotPaused) { return };
    // Process incoming message
    ...

Note for Botkit users: If you are using Botkit, you do not need to call to hopIn. Instead, you can add the wordhop middleware. Then your message object will have a paused property. Here's an example:

controller.middleware.receive.use(wordhop.receive);
// reply to a direct message
controller.on('direct_message', function (bot, message) {
    // If your bot is paused, stop it from replying
    if (message.paused) { return };
    // Process incoming message
    ...

Each time your bot sends a message, make sure to log that with Wordhop by calling to wordhop.hopOut. Here is an example of a function that we're calling sendIt that tracks an outgoing message and at the same time, has the bot say the message:

var sendIt = function(outgoingMessage) {
    wordhop.hopOut(outgoingMessage);
    bot.say(outgoingMessage); // <= example of bot sending reply
    ...

Note: If you are using Botkit, you do not need to call to hopOut. Instead, you can add the following middleware:

controller.middleware.send.use(wordhop.send);

Find the spot in your code your bot processes incoming messages it does not understand. Within that block of code, call to wordhop.logUnkownIntent to capture these conversational ‘dead-ends’. Here's an example:

// let the user know that the bot does not understand
var outgoingMessage = {'channel':channel,'text':'Huh?'}; // <= Schema matches Slack
sendIt(outgoingMessage);
// capture conversational dead-ends.
wordhop.logUnknownIntent(incomingMessage);

Wordhop can trigger alerts to suggest when a human should take over for your Chatbot. To enable this, create an intent such as when a customer explicitly requests live assistance, and then include the following lines of code where your bot listens for this intent:

// match an intent to talk to a real human
if (text == 'help') {
    // let the user know that they are being routed to a human
    var outgoingMessage = {'channel':channel,'text':'Hang tight. Let me see what I can do.'};  // <= Schema matches Slack
    sendIt(outgoingMessage);
    // send a Wordhop alert to your slack channel
    // that the user could use assistance
    wordhop.assistanceRequested(incomingMessage);

To enable the ability to have a human take over your bot, add the following code:

// Handle forwarding the messages sent by a human through your bot
wordhop.on('chat response', function (outgoingMessage) {
    bot.say(outgoingMessage);  // <= example of bot sending message
});

Go back to Slack and wait for alerts. That's it! Be sure to check out our examples.

• Join our mailing list and we'll notifiy you
• Contact Support