LivePerson Bot Adapter

This is a sample bot to feature the LivePerson Bot adapter that enables the integration of the Microsoft Bot Framework to the LivePerson care agent system. In addition to simply reviewing and sending messages, with the help of the LivePerson Agent SDK the adapter unlocks all the features of the LivePerson service, such as transferring the conversation to a human care agent. Note that for some features additional code may be required.

The code here is an extract from a larger piece of work created by my awesome team mates, Martin Kearn, Marek Lani and yours truly. Special kudos to Marek for writing the rich content translation bit.

Getting started

0. Prerequisites:

   • Download and install Node.js
   • Access to LivePerson system to test the LivePerson adapter - LivePerson offers a 30 day free trial

1. Install required packages and compile to JavaScript:

   npm install --save
   tsc
   

   You can also use the setup scripts that come with the project. How convenient!

2. Insert LivePerson credentials to

   • environment variables directly OR
   • run scripts (run.sh or run.bat) OR
   • VS Code launch configuration

3. Run locally to see that everything works

   node main.js
   

   Or use the run scripts or the VS Code launch configuration to run using the IDE.

4. Play with the code, deploy etc.

Implementation

The heart of the project is the adapter class itself: LivePersonBotAdapter. The key principle of this approach is that one can simply replace the typically used BotFrameworkAdapter with the LivePersonBotAdapter class. You can also run both in parallel! For example, you can reach the channels not supported by LivePerson using the Microsoft Bot Connector service. What makes this approach nice is that no changes to the bot conversational logic (code) is required!

Using BotFrameworkAdapter:

const botFrameworkAdapter = new BotFrameworkAdapter({ 
    // Bot Framework credentials
});

botFrameworkAdapter.use(myMiddleware);

// server is a restify server
server.post("/api/messages", (request, response) => {
    botFrameworkAdapter.processActivity(request, response, async (context) => {
        // Bot logic code
    });
});

Using LivePersonBotAdapter:

const livePersonBotAdapter = new LivePersonBotAdapter({
    // LivePerson credentials
});

livePersonBotAdapter.use(myMiddleware);

livePersonBotAdapter.getListener().on(LivePersonAgentListener.MESSAGE, async (context) => {
    (context.adapter as LivePersonBotAdapter).runMiddleware(context, async (context) => {
        // Bot logic code
    });
});

See app.ts for reference.

Unsurprisingly, the format of the messages (protocol if you will) differ between the LivePerson system and the Bot Framework. It is the content translation that allows us to share common code for the bot logic regardless of which adapter class we use.

The LivePersonBotAdapter class does the content translation from the LivePerson format into the Bot Framework format. The incoming messages are translated in the LivePersonAgentListener class and the outgoing in the sendActivities method of the LivePersonBotAdapter class by the content translator.

Although the bot logic code is shared, when using both the LivePerson and the Bot Framework Connector service, you might still want to differentiate the bot behaviour depending on the adapter. LivePerson enables features such as transferring the chat to another agent, which the Bot Framework Connector cannot do by default - to address situations like this in the bot logic code, you can apply the following approach:

const isViaLivePerson: boolean = (turnContext.adapter instanceof LivePersonBotAdapter);

if (isViaLivePerson) {
    // LivePerson specific code here
} else {
    // Bot Framework Connector alternative
}

In addition, the channel ID value of activities (context.activity.channelId) originated from LivePerson is 'liveperson'. See contenttranslator.ts.

Disclaimer: The LivePersonBotAdapter and the content translation is not 100 %. Currently ContentTranslator supports translation of Hero Cards containing text, images and buttons (including URL links), Carousels and Suggested Actions. Translation of Adaptive Cards is not supported yet. Note, that you need to whitelist image and link URLs within your LivePerson account, so images are displayed and buttons are navigating to desired URL. Test your scenarios (especially related to rich content) and implement the gaps missing. Pull requests for such contributions are very welcome and much appreciated!

Resources

• Microsoft Bot Framework developer documentation
• LivePerson developer documentation
• LivePerson Agent Messaging SDK for Node.js