readme.md

botkit-plugin-cms

Use and extend dialogs authored remotely using Botkit CMS.

Install Package

Add this package to your project using npm:

npm install --save botkit-plugin-cms

Import the adapter class into your code:

const { BotkitCMSHelper } = require('botkit-plugin-cms');

Use in your App

Configure the plugin with the URI of your Botkit CMS instance and a token set in the CMS config. These values are available from the cms admin dashboard's options tab.

Then, register the plugin and it's features with the Botkit controller using usePlugin()

let cms = new BotkitCMSHelper({
    uri: 'https://someurl.com/',
    token: 'some-token-value'
});

controller.usePlugin(cms);

Once registered, Botkit will automatically load all of the available content from the Botkit CMS api and dynamically create BotkitConversation Dialogs for use in The bot. All of the plugin's methods will be available at controller.plugins.cms.

To evaluate all incoming messages for triggers configured in the CMS, and automatically respond by starting the appropriate dialog, use controller.plugins.cms.testTrigger():

// use the cms to test remote triggers
controller.on('message', async(bot, message) => {
  let triggered = await controller.plugins.cms.testTrigger(bot, message);
  
  // if a script was triggered, return false from the handler.
  // this stops botkit from any further processing.
  if (triggered !== false) {
      return false;
  }
});

In most cases, calls to testTrigger should come at the end of the bot's message evaluation process. Since Botkit fires handlers in the order in which they are added to the controller, this call should most often be placed after other trigger definintions - particularly if the CMS has been configured with a fallback script which will ALWAYS fire even if no matching trigger is found.

Hooking code to your CMS-powered Dialogs

Since under the hood, this plugin creates BotkitConversation Dialogs, all of the same hooks, templating features, and special actions are available. However, since the dialogs are built dynamically, special methods are necessary to find the dialog by name within Botkit's collection of dialogs before binding hooks.

• controller.plugins.cms.before()
• controller.plugins.cms.onChange()
• controller.plugins.cms.after()

For example, if the CMS has a script called onboarding, hook functions can be bound to it like so:

// wrap calls to the plugin in controller.ready to ensure the content has successfully loaded
controller.ready(function() {

    // fire before onboarding begins
    controller.plugins.cms.before('onboarding', async(convo, bot) => {
        convo.setVar('timestamp', new Date());
    });

    // fire after onboarding ends
    controller.plugins.cms.after('onboarding', async(results, bot) => {
        // do something like store results in the db

        // take the next step...
        await bot.say('ONBOARDING COMPLETE!');
    });
});

Class Reference

• BotkitCMSHelper

About Botkit

Botkit is a part of the Microsoft Bot Framework.

Want to contribute? Read the contributor guide

Botkit is released under the MIT Open Source license