Intermediator Bot Sample

This is a sample bot, built with the Microsoft Bot Framework (v4),
that routes messages between two users on different channels. This sample utilizes the
Bot Message Routing (component) project.
The general gist of the message routing is explained in this article:
Chatbots as Middlemen blog post.

A possible use case for this type of a bot would be a customer service scenario where the bot relays
the messages between a customer and a customer service agent.

This is a C# sample targeting the latest version (v4) of the Microsoft Bot Framework. The sample
did previously target the v3.x and you can find that last release
here.

If you prefer Node.js, fear not, there are these two great samples to look into:

• botframework-v4-handoff
• Bot-HandOff (v3)

Contents

• Getting started
• Deploying the bot
• App settings and credentials
• Testing the hand-off
• About the implementation
• Custom agent portal
• Helpful links

Getting started

Since this is an advanced bot scenario, the prerequisites include that you are familiar with the
basic concepts of the Microsoft Bot Framework and you know the C# programming language. Before
getting started it is recommended that you have the following tools installed:

• Visual Studio IDE
• ngrok
• Bot Framework Emulator (download)
  • Debug bots with the Bot Framework Emulator

Altough the bot can be practically hosted anywhere, the deployment instructions (below) are for
Azure. If you don't have an Azure subscription yet, you can get one for free here:
Create your Azure free account today.

Deploying the bot

This sample demonstrates routing messages between different users on different channels. Hence,
using only the emulator to test the sample may prove difficult. To utilize other channels, you must
first compile and publish the bot:

1. Open the solution (IntermediatorBotSample.sln) in Visual Studio/your IDE and make sure it
   compiles without any errors (or warnings)
2. Follow the steps in this article carefully:
   Deploy your bot to Azure
   • Top tip: Create a new Azure resource group
     for the app so that if stuff goes wrong, it's really easy to just delete the whole group and
     start over
   • Having issues testing the bot (as in "The dang thing doesn't work!!") - check the following:
     • Did you remember to include /api/messages in the messaging endpoint
       (Bot Channels Registration/Settings)?
     • Did you remember to create and add the credentials (MicrosoftAppId and MicrosoftAppPassword)?
3. Add the credentials (MicrosoftAppId and MicrosoftAppPassword) to the
   appsettings.json file and republish the bot - now
   all you need to do to republish is to right-click the app project in the Solution Explorer in
   Visual Studio, select Publish... and click the Publish button on the tab (named in the
   sample "IntermediatorBotSample").

App settings and credentials

App settings and credentials are available in the
appsettings.json
file of this sample. The file contains both bot and storage credentials as well as the settings that
can be used to tailor the experience. The default content of the file looks something like this:

{
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "BotBasePath": "/api",
  "BotMessagesPath": "/messages",
  "AzureTableStorageConnectionString": "",
  "RejectConnectionRequestIfNoAggregationChannel": true,
  "PermittedAggregationChannels": "",
  "NoDirectConversationsWithChannels": "emulator, facebook, skype, msteams, webchat"
}

Settings

• BotBasePath and BotMessagesPath can be used to define the messaging endpoint of the bot. The
  endpoint by default is http(s)://<bot URL>/api/messages.
• RejectConnectionRequestIfNoAggregationChannel defines whether to reject connection requests
  automatically if no aggregation channel is set or not. Pretty straightforward, don't you think?
• PermittedAggregationChannels can be used to rule out certain channels as aggregation channels.
  If, for instance, the list contains facebook, the bot will refuse to set any Facebook
  conversation as an aggregation channel.
• The solution allows the bot to try and create direct conversations with the accepted "customers".
  NoDirectConversationsWithChannels defines the channels where the bot should not try to do this.

Credentials

• MicrosoftAppId and MicrosoftAppPassword should contain the bot's credentials, which you
  acquire from the Azure portal when you publish the bot.
• The bot needs to have a centralized storage for routing data. When you insert a valid Azure Table
  Storage connection string as the value of the AzureTableStorageConnectionString property, the
  storage automatically taken in use.

Testing the hand-off

This scenario utilizes an aggregation concept (see the terminology table in this document). One or
more channels act as aggregated channels where the customer requests (for human assistance) are
sent. The conversation owners (e.g. customer service agents) then accept or reject the requests.

Once you have published the bot, go to the channel you want to receive the requests and issue the
following command to the bot (given that you haven't changed the default bot command handler or the
command itself):

@<bot name> watch

In case mentions are not supported, you can also use the command keyword:

command watch

Now all the requests from another channels are forwarded to this channel.
See the default flow below:

Teams	Slack

Commands

The bot comes with a simple command handling mechanism, which supports the commands in the table
below.

To issue a command use the bot name:

@<bot name> <command> <optional parameters>

In case mentions are not supported, you can also use the command keyword:

command <command> <optional parameters>

Although not an actual command, typing human will initiate a connection request, which an agent
can then reject or accept.

Implementation

The core message routing functionality comes from the
Bot Message Routing (component) project.
This sample demonstrates how to use the component and provides the necessary "plumbing" such as
command handling. Here are the main classes of the sample:

• HandoffMiddleware: Contains all the
  components (class instances) required by the hand-off and implements the main logic flow. This
  middleware class will check every incoming message for hand-off related actions.
• CommandHandler:
  Provides implementation for checking and acting on commands in messages before they are passed to
  a dialog etc.
• MessageRouterResultHandler:
  Handles the results of the operations executed by the MessageRouter of the Bot Message
  Routing component.
• ConnectionRequestHandler:
  Implements the main logic for accepting or rejecting connection requests.

What if I want to have a custom agent portal/channel?

Well, right now you have to implement it. There are couple of different ways to go about it. It's
hard to say which one is the best, but if I were to do it, I'd propably start by...

1. ...implementing a REST API endpoint
   (see for instance Create a Web API with ASP.NET Core).
   Then I'd hook the REST API into the message routing code and finally removed the text based
   command handling altogether.
2. Another options is to use back channel messages and hook them up into the current command
   pipeline. Granted some changes would need to be made to separate the direct commands from the
   back channel ones. Also, the response would likely need to be (or recommended to be) in JSON.
3. Something else - remember, it's just a web app!

See also

• Bot Message Routing (component) project
  • NuGet package
• Chatbots as Middlemen blog post