A bot build on Microsoft Bot Framework that routes messages between two users on different channels. This is sample utilizes the core functionality found in Bot Message Routing (component) project.

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 - if you're looking to do this with Node, see this sample.

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 installed the following tools:

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

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 publish the bot:

1. Go to the Azure Portal
2. Create a new Bot Service (Web App Bot is the recommended type for this sample)
3. Collect the application ID and application password of the newly created Bot Service
4. Copy and rename the application settings and credentials template file (AppSettingsAndCredentials.config.template) by removing the .template postfix
5. Open the solution file (IntermediatorBotSample.sln) in Visual Studio
6. Insert the settings and credentials into AppSettingsAndCredentials.config file
   • See App settings and credentials section for more details
7. Build the solution and publish (right-click the IntermediatorBotSample project in the Solution Explorer in Visual Studio and select Publish)
   • For more details, see Publish a bot to Bot Service

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:

Emulator with ngrok	Slack

BETA - Help wanted!

In this scenario the conversation owners (e.g. customer service agents) access the bot via the webchat component, Agent UI, implemented by Bill Barnes. Each customer request (for human assistance) automatically opens a new chat window in the agent UI.

Emulator	Agent UI

To set this up, follow these steps:

0. Make sure you have Node.js installed

1. Clone or download the Agent UI repository

2. Inside index.ts, update the line below with your bot's endpoint:

   fetch("http://YOUR_BOT_ENDPOINT/api/agent/1")

   Example: fetch("http://mybot.azurewebsites.net/api/agent/1")

3. Inside index.ts, update the line below with your bot secret key (which you can find in your Bot Service)

   iframe.src = 'botchat?s=YOUR_DIRECTLINE_SECRET_ID';

4. Run npm install to get the npm packages

   • You only need to run this command once, unless you add other node packages to the project
   • If you encounter error TS2300, run npm install typescript@2.0.10

5. Run npm run build to build the app

   • You need to run this every time you make changes to the code before you start the application

6. Run npm run start to start the app

7. Go to http://localhost:8080 to see the Agent UI

Make sure that the value of RejectConnectionRequestIfNoAggregationChannel key in Web.config is false:

<add key="RejectConnectionRequestIfNoAggregationChannel" value="false" />

Otherwise the agent UI will not receive the requests, but they are automatically rejected (if no aggregation channel is set).

The bot comes with a simple command handling mechanism, which implements 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.

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.

Command handling

• BackChannelMessageHandler: Provides implementation for checking and acting on back channel (command) messages. Back channel messages are used by the agent UI.

• CommandMessageHandler: Provides implementation for checking and acting on commands in messages before they are passed to a dialog etc.

Controllers

• AgentController: A controller for the agent UI. Enables the agent UI to check the status of pending requests and automatically accept them.

• MessagesController: This class is included in the bot project template. In this sample it is beneficial to look into how to the command handling and message routing implementations integrate into the bot code (see the Post method).

Message routing (utils)

• MessageRouterResultHandler: Handles the results of the operations executed by MessageRouterManager.

App settings and credentials are available in the Web.config file of this sample. The settings can be used to tailor the experience.

The credentials (and the bot ID) can be placed either directly in the Web.config file (not recommended when the code is managed in a repository to avoid accidentally leaking them there) or in the separate AppSettingsAndCredentials.config file in the IntermediatorBotSample folder of the project (recommended). The content of the AppSettingsAndCredentials.config file is added into the Web.config when the project is built. The format of the AppSettingsAndCredentials.config file is as follows:

<appSettings>
  <!-- Update these with your BotId, Microsoft App Id and your Microsoft App Password-->
  <add key="BotId" value="" />
  <add key="MicrosoftAppId" value="" />
  <add key="MicrosoftAppPassword" value="" />

  <!-- Add your connection string for routing data storage below -->
  <add key="RoutingDataStorageConnectionString" value="" />
</appSettings>

Note that since the AppSettingsAndCredentials.config file is not included in the repository, you must create the file. A template file is provided for your convenience. Simply remove the .template postfix and fill in the details.

RejectConnectionRequestIfNoAggregationChannel: This setting, which is set to true by default, will cause the IRoutingDataManager implementation to return the NoAgentsAvailable result when no agents are watching for incoming requests. You can then send an appropriate response to let the user know no agents are available within the implementation of your MessageRouterResult handler. If this is set to false, then the IRoutingDataManager implementation will process and add the user's request to the pending requests list and return the ConnectionRequested result instead.

<add key="RejectConnectionRequestIfNoAggregationChannel" value="false" />

PermittedAggregationChannels: If you wish to only allow conversation owners (i.e. customer service agent) to use a specific channel or channels, you can specify a comma separated list of channel IDs here. This will prevent agent commands from being used on other channels and prevent users from accidentally or deliberately calling such commands. If you leave the value empty, all channels are considered permitted. If, for instance, you wanted to restrict the agents to use the emulator and Skype channels, you would use:

<add key="PermittedAggregationChannels" value="emulator,skype" />

The provided BotSettings utility class can be used to easily access the settings in the code.

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