hivekit-plugin-cms v1.0.4

hivekit-plugin-cms

Use and extend dialogs authored remotely using Hivekit CMS.

Install Package

Add this package to your project using npm:

npm install --save hivekit-plugin-cms

Import the adapter class into your code:

const { HivekitCMSHelper } = require('hivekit-plugin-cms');

Use in your App

Configure the plugin with the URI of your Hivekit 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 Hivekit controller using usePlugin()

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

controller.usePlugin(cms);

Once registered, Hivekit will automatically load all of the available content from the Hivekit CMS api and dynamically create HivekitConversation 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 hivekit 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 Hivekit 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 HivekitConversation 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 Hivekit'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

• HivekitCMSHelper

About Hivekit

Hivekit is a part of the Microsoft Bot Framework.

Want to contribute? Read the contributor guide

Hivekit is released under the MIT Open Source license