botbuilder-handoff
A common request from companies and organizations considering bots is the ability to "hand off" a customer from a bot to a human agent, as seamlessly as possible.
This project implements a framework called Handoff which enables bot authors to implement a wide variety of scenarios, including a full-fledged call center app, with minimal changes to the actual bot.
It also includes a very simple implementation that illustrates the core concepts with minimal configuration.
This project is in heavy flux, but is now in a usable state. However this should still be considered a sample, and not an officially supported Microsoft product.
This project is written in TypeScript.
Source Code
See example folder for a full bot example.
Basic Usage
const express = require('express');
const builder = require('botbuilder');
const handoff = require('botbuilder-handoff');
const app = express();
app.listen(process.env.port || process.env.PORT || 3978, '::', () => {
console.log('Server Up');
});
const isAgent = (session) => session.message.user.name.startsWith("Agent");
handoff.setup(bot, app, isAgent, {
mongodbProvider: process.env.MONGODB_PROVIDER,
directlineSecret: process.env.MICROSOFT_DIRECTLINE_SECRET,
textAnalyticsKey: process.env.CG_SENTIMENT_KEY,
appInsightsInstrumentationKey: process.env.APPINSIGHTS_INSTRUMENTATIONKEY,
retainData: process.env.RETAIN_DATA,
customerStartHandoffCommand: process.env.CUSTOMER_START_HANDOFF_COMMAND
});
You can also manually trigger a handoff using the following example. Make sure you run handoff.setup(...)
first.
bot.dialog('/connectToHuman', (session)=>{
session.send("Hold on, buddy! Connecting you to the next available agent!");
handoff.triggerHandoff(session);
}).triggerAction({
matches: /^agent/i,
});
Settings
You can either provide these settings in the options of handoff.setup()
or just provide them as environment variables.
mongodbProvider
{mongodbProvider: process.env.MONGODB_PROVIDER}
mongodbProvider is a required field. This is your mongodb connection string.
directlineSecret
{directlineSecret: process.env.MICROSOFT_DIRECTLINE_SECRET}
directlineSecret is a required field. This is your bot's direct line sectet key; you can get this from the bot framework portal when you setup the direct line channel.
textAnalyticsKey
{textAnalyticsKey: process.env.CG_SENTIMENT_KEY}
textAnalyticsKey is optional. This is the Microsoft Cognitive Services Text Analytics key. Providing this value will result in running sentiment analysis on all user messages, saving the sentiment score to the transcript in mongodb.
appInsightsInstrumentationKey
{appInsightsInstrumentationKey: process.env.APPINSIGHTS_INSTRUMENTATIONKEY}
appInsightsInstrumentationKey is optional. This is the Microsoft Application Insights Instrumentation Key. Providing this value will result in logging most values of the conversation object to application insights as a custom event called 'Transcript'.
The values logged to application ingsights are:
botId
customerId
customerName
customerChannelId
customerConversationId
agentId
agentName
agentChannelId
agentConversationId
retainData
{ retainData: process.env.RETAIN_DATA }
retainData is optional. If you want to keep the data after a hand off, you must add this environment variable/option. Otherwise, after an agent disconnects from talking to the user, the entire conversation object will be deleted from the database. This can be "true"
or "false"
.
customerStartHandoffCommand
{customerStartHandoffCommand: process.env.CUSTOMER_START_HANDOFF_COMMAND}
customerStartHandoffCommand is optional. This is the command that a user (customer, not agent) can type to start the handoff which will queue them to speak to an agent. The default command will be set to "help"
. Regex is used on this command to make sure the activation of the handoff only works if the user types the exact phrase provided in this property.
Required environment variables:
"MICROSOFT_APP_ID" : "",
"MICROSOFT_APP_PASSWORD" : "",
"MICROSOFT_DIRECTLINE_SECRET" : "",
"MONGODB_PROVIDER" : ""
Optional environment variables:
"CG_SENTIMENT_KEY" : "",
"APPINSIGHTS_INSTRUMENTATIONKEY" : "",
"RETAIN_DATA: "true" or "false"
"CUSTOMER_START_HANDOFF_COMMAND" : ""
Sample Webchat
If you want the sample /webchat
endpoint to work (endpoint for the example agent / call center), you will need to include this public
folder in the root directory of your project, or replace with your own.
License
MIT License