Custom Bot Builder

WhosOn Custom Bot

Introduction

You can create a WhosOn Custom Bot that runs on your WhosOn Server. This is useful if you want to access on-premises resources, or customise your interactions with the NLU services.

Example use cases

a hybrid bot that can check customer order numbers against your database whenever they are mentioned in the chat
a bot that can act on custom actions returning from AWS to create tickets in your ticketing system
a bot that can look up common answers in your own knowledge base using an API

Guide

This guide creates a simple bot that reverses the input text that you say to it.

Prerequisites

Visual Studio
A working WhosOn 19 installation

Steps

Launch Visual Studio
Create a new Microsoft .NET v4.6.2 class library
Add the nuget package "Parkersoft.WhosOn.BotConnector".
This includes the interfaces that you need to implement for your custom bot to interact with the WhosOn server.

Create a new class which implements the IBot interface. The instances of the class relate to a single Bot inside the WhosOn Bot service, but can have many conversations ongoing at the same time. You can use whatever namespace you wish here.

using Parkersoft.WhosOn.BotConnector;
  using Parkersoft.WhosOn.BotConnector.Message;

  namespace WhosOnBot
  {
      public class CustomBot : IBot
      {

      }
  }

Copy

First, implement the UniqueName property as a simple property. This is where the bot's username is stored if you need to use it.

public string UniqueName {get; set;}

Copy

Implement the OnBotMessage delegate. This is the delegate that the consumer of your class will register against to receive messages from your bot code. The consumer of your class is the WhosOn Bot Service.

public Delegates.BotMessage OnBotMessage {get; set;}

Copy

Implement the CreateConversation function. This function is where you would put any code that is executed when your conversation starts. For our example, we don't need anything here, so we just return true.

public bool CreateConversation(string conversationId, IDictionary<string, string> properties)
  {
      return true;
  }

Copy

Implement the EndConversation function. This function is where you would put any clean up code for a particular conversation after the visitor closes the session, or the Bot hands the conversation off to another user. For our example we don't need this to do anything.

public bool EndConversation(string conversationId)
  {
      return true;
  }

Copy

Implement the AddProperties function. This function is called whenever any properties are changed. This is usually called when you are collecting dynamic survey fields from customers. Again, we don't need this for our example.

public void AddProperties(string conversationId, IDictionary<string, string> properties)
  {
      return;
  }

Copy

Now we get to the main function that processes the chat messages. SendMessage receives a line of text, and can then respond to the customer. Note that you don't have to respond, but you should return true unless you want the WhosOn Bot Service to attempt a default fallback response. Here we will call the SendBotMessageAsync helper function (which in turn calls the OnBotMessage) with our reversal message. We use the text message type to send a message back to the end user.

public bool SendMessage(string conversationId, string message)
  {
      var charArr = message.ToCharArray();
      System.Array.Reverse(charArr);
      this.SendBotMessageAsync(conversationId, new BotTextMessage() { Text = new string(charArr) });
      return true;
  }

Copy

Now we have to expose to the WhosOn Bot Service how to create an instance of the bot. For this we implement the IBotCreator interface.

using Parkersoft.WhosOn.BotConnector;

  namespace WhosOnBot
  {
      public class CustomBotCreator : IBotCreator
      {

Copy

Implement the BotType property. This is the name that needs to be put in the settings portal to load your type of bot into the bot service. It doesn't need to match your class name.

public string BotType => "CustomBot";

Copy

Implement the DoCreateBot delegate getter. Here we return a function that is responsible for creating a bot.
This is structured in this way to allow the reflection inside the Bot Service to find all instances of Bot Creators and create a bot from that function. The delegate CreateBot has a single parameter for the BotSettings and returns an instance of a class that implements IBot.

public Delegates.CreateBot DoCreateBot
  {
      get
      {
          return ((x) =>
          {
              return new CustomBot();
          });
      }
  }

Copy

BotSettings is a key table that contains any startup properties for the bot creation.

Now we have created our bot, compile it. The DLL needs to follow the naming pattern Parkersoft.WhosOn.BotConnector.{botname}.dll. The name doesn't need to match your bot type. Take the DLL that is created, and drop it into the Bot Services "Connectors" folder.
In the settings portal, you can now setup your bot. Login is an Admin user, go to your users -> bots area, and create a new bot.
In the Bot Platform, select "WhosOn Custom Bot" from the drop down.

In the Assistant ID field, enter the Bot Type that you set in the Bot Creator.
Save your bot.
Restart your WhosOn Bot Service so that the connectors are reloaded.
Test it out.

Additional Notes

Sample source code

Sample source code is available on github.
https://github.com/Parker-Software/WhosOn-Custom-Bot

Dependencies

If your Bot Connector has dependencies as part of the build, you should put these into a subfolder with the same name as your bot assembly name.

If your assembly name is "CustomBot" then you put the CustomBot.dll into the "Connectors" folder, and make a subfolder here named "CustomBot". All the dependencies go into the "CustomBot" subfolder.

Custom bot options

You can enter a JSON object in the custom bot options. This should be key value pairs like:

{
      "url": "https://www.test.com/service",
      "api-key": "1231412331231231241412313"
  }

Copy

You can extract these from the BotSettings object during bot creation.