botkit-middleware travis-ci npm

A middleware to connect Watson Conversation Service to different chat channels using Botkit

3 years after

Use IBM Watson's Conversation service to chat with your Botkit-powered Bot! Build Status

This middleware plugin for Botkit allows developers to easily integrate a Watson Conversation workspace with multiple social channels like Slack, Facebook, and Twilio. Customers can have simultaneous, independent conversations with a single workspace through different channels.

Middleware Overview

  • Automatically manages context in multi-turn conversations to keep track of where the user left off in the conversation.
  • Allows greater flexibility in message handling.
  • Handles external databases for context storage.
  • Easily integrates with third-party services.
  • Exposes the following functions to developers:
    • before: pre-process requests before sending to Watson Conversation (Conversation).
    • after : post-process responses before forwarding them to Botkit.


$ npm install botkit-middleware-watson --save


Acquire Watson Conversation credentials

The middleware needs you to provide the username, password, and workspace_id of your Watson Conversation chat bot. If you have an existing Conversation service instance, follow these steps to get your credentials.

If you do not have a Conversation service instance, follow these steps to get started.

Acquire channel credentials

This document shows code snippets for using a Slack bot with the middleware. (If you want examples for the other channels, see the examples/multi-bot folder. The multi-bot example app shows how to connect to Slack, Facebook, and Twilio IPM bots running on a single Express server.)

You need a Slack token for your Slack bot to talk to Conversation.

If you have an existing Slack bot, then copy the Slack token from your Slack settings page.

Otherwise, follow Botkit's instructions to create your Slack bot from scratch. When your bot is ready, you are provided with a Slack token.

Bot setup

This section walks you through code snippets to set up your Slack bot. If you want, you can jump straight to the full example.

In your app, add the following lines to create your Slack controller using Botkit:

var slackController = Botkit.slackbot();

Spawn a Slack bot using the controller:

var slackBot = slackController.spawn({

Create the middleware object which you'll use to connect to the Conversation service:

var watsonMiddleware = require('botkit-middleware-watson');

Tell your Slackbot to use the watsonMiddleware for incoming messages:


Finally, make your bot listen to incoming messages and respond with Watson Conversation:

slackController.hears(['.*'], ['direct_message', 'direct_mention', 'mention'], function(bot, message) {
    bot.reply(message, message.watsonData.output.text.join('\n'));

The middleware attaches the watsonData object to message. This contains the text response from Conversation.

Then you're all set!

Using before and after functions

The before and after callbacks are available through the Watson middleware object.

var middleware = require('botkit-middleware-watson');

These can be customized as follows:

middleware.before = function(message, conversationPayload, callback) {
    // Code here gets executed before making the call to Conversation.
    callback(null, customizedPayload);
  middleware.after = function(message, conversationResponse, callback) {
    // Code here gets executed after the call to Conversation.
    callback(null, conversationResponse);

This comes in handy to:

  • Make database updates
  • Update the context in the payload
  • Call some external service before/after calling Conversation


This library is licensed under Apache 2.0. Full license text is available in LICENSE.

Related Repositories



Botkit is a toolkit for making bot applications ...



Official Facebook Messenger connector for Botpress ...



Middleware for using with Botkit-powered bots ...



A deep work slackbot using Express to manage requests and serve webpages ...



Middleware for using with Botkit-powered bots ...

Top Contributors

germanattanasio aarora91 Naktibalda stevenoh93 benbrown eubruno dgterry toxuin ambercraig


-   v1.4.2 zip tar
-   v1.4.1 zip tar
-   v1.4.0 zip tar
-   v1.3.1 zip tar
-   v1.2.0 zip tar
-   v1.0.0 zip tar