Skip to main content

NodeJS Bot Agent Connector—Azure Web App Bot (Quick Start Guide)

  • Chat

Updated ~ minute read

Introduction

The Bot Agent Connector allows you to develop bots as Live Assist for Microsoft Dynamics 365 agents.

  • The only bots that are supported are from Microsoft’s Bot Framework, using the Direct Line connector.
  • Bots created in this way can handle visitor chats, and transfer to another agent when required.

This article provides instructions to familiarize yourself with the Microsoft Azure Bot framework, and how to register Bots against your Live Assist for Microsoft Dynamics 365 account.

The bot shown here simply replies to any chat messages that the visitor to an engagement sends to the bot. The engagement is configured to target a specific skill group, to isolate the bot from other agents in your organization. When the visitor sends transfer to MySkill, the bot allows the chat to be transferred to another skill group with human agents assigned to it.

Requirements

To produce Bots as Agents you need the following:

  • A Live Assist for Microsoft Dynamics 365 license.
    Each bot can handle 3 concurrent chats for each Live Assist Enhanced license allocated.
  • A Microsoft Azure Subscription, with access to the Azure Bot Service.
    You can register for a free trial

Step 1—Creating a Web App Bot

  • Create a Web App Bot resource in Azure.
    • The Bot Name must be unique and select NodeJS Basic.
    • Select an appropriate Pricing Tier for your bot—we use F0 for development, as it has little running costs.
      2018-05-02 16_57_25-Web App Bot - Microsoft Azure.png

Step 2—Applying the NodeJS Code Changes

  1. Under Build > Open online code editor > App Service Editor you can view the executing code.
    2018-05-03 11_28_23-Choose how to work with your code - Microsoft Azure.png
  2. Modify the app.js that comes with the Basic Web App Bot.
    Screen Shot 2018-06-08 at 13.26.48.png
  3. Make the following code changes:
    1. Define a constant string: 
      const TRANSFER_MESSAGE = 'transfer to ';
    2. Within the root bot.dialog('/') function, handle the communication between the visitor and the Bot with something like this switch statement:    
      switch(session.message.sourceEvent.type)
    {
        case "visitorContextData":
            //process context data if required. This is the first message received so say hello.
            session.send('Hi, I am an echo bot and will repeat everything you said.');
            break;

        case "systemMessage":
            //react to system messages if required
            break;

        case "transferFailed":
            //react to transfer failures if required
            break;

        case "otherAgentMessage":
            //react to messages from a supervisor if required
            break;

        case "visitorMessage":
            // Check for transfer message
                        if(session.message.text.startsWith(TRANSFER_MESSAGE)){
                                var transferTo = session.message.text.substr(TRANSFER_MESSAGE.length);
                                var msg = new builder.Message(session).sourceEvent({directline: {type: "transfer", agent: transferTo}});
                                session.send(msg);
                        }else {
                                session.send('You said ' + session.message.text);
                        }
            break;

        default:
            session.send('This is not a Live Assist message ' + session.message.sourceEvent.type);
    }
    3. Most of the Bot is left unchanged. The switch statement'and the 'VisitorMessage' case provides most of the significant code.
      Our bot simply relays the Message received back to the consumer unless they type: 'transfer to <skill_name>'. 

See also:

Step 3—Creating a Direct Line Channel Connector

See: Creating a Direct Line Channel Connector

Step 4—Configuring an Engagement

If you are developing bots on a production organization, be aware that the bot may answer any chats that are started, unless the bot user is allocated to a Skill Group within the Engagement Portal, then set up an engagement that routes to this skill.

  1. In the Engagement Portal, create a new Skill called BotSkill:
    NodeJS
  2. Allocate the skill to the Bot User:
    NodeJS
  3. Assign the BotSkill to the Engagement:
    NodeJS
  4. In the same way, create a Skill Group MySkill and assign it to one of your human agents, to test the transfer.
    NOdeJS

Step 6—Testing the Bot

The bot is now ready to test using Live Assist for Microsoft Dynamics 365 engagement.

Note: You can use the Trial Engagement for testing if required.

  1. Visitor Side:
    Screenshot
  2. When the User types: 'transfer to MySkill' the chat is routed through to the MySkill Group and the assigned Agent can answer it:
    Screenshot

Debugging Web App Bots

There are numerous ways to debug your bot application. The following Microsoft documents may assist you with this:

Pre-Chat Survey

If your engagement has a pre-chat survey, the information collected is available to an agent in the Chat Activity, after the bot has transferred the chat.

Screenshot

Post-chat Survey

Information collected on a post-chat survey is added to the Chat Activity

2018-05-16 10_09_58-Chat Activity_ Chat with Dev.png

The transcript clearly labels the bot, agent, and visitor, as well as other Information.

2018-05-16 10_10_33-Your chat transcript - thill@cafex.com - Cafex Communications Mail.png

Introduction

The Bot Agent Connector allows you to configure bots to act as Live Assist for Dynamics 365 agents. At the moment, only bots from Microsoft’s Bot Framework (using the Direct Line connector) are supported.

This guide aims to give step by step instructions on how to create a very simple bot from scratch (In Microsoft’s Bot Framework) and integrate it into Live Assist for Dynamics 365. We will use the Node.js sample but you will get the option to select .NET if you prefer (although that will not be covered here).

Requirements

  • Live Assist for Dynamics 365 (with at least one available licence)

  • Microsoft Azure Subscription - to allow you to use the Azure Bot Service. If you do not have a subscription, you can register for a free trial.

Steps

Microsoft provides a tutorial for setting up a Bot Service: Create a bot with Bot Service.  We have used this guide to create a NodeJS Bot, using a Consumption Plan. Our bot was titled: botechdemo.

Here are the additional steps creating the NodeJS Bot:
 

  1. Select the NodeJS option, Basic and read the terms, privacy statement and code of conduct. If you agree to these select the checkbox and press the create bot button.
    Demonstration on how to select NodeJS from the language list
  2. Once the bot has been created you should see the code for a file called index.js in your browser. Take the code sample below and replace the contents of this file with it.
  3. The screenshot below shows the differences between the snippet and the default bot.

The changes do two things:

Messages sent by the consumer are checked for the pattern transfer to x. If a message in this format is found, then a transfer is requested to the user with name x. The message source event type is also checked. This attribute describes various types of messages which can be received in certain situations. See the comments for what each message type relates to.

screenshot.png


After making the code changes, click Save.

Building the Bot on .NET

To force a rebuild of the bot dialog, run the following:

  1. Open the console:Click the Open Console button
  2. Run the command msbuild:
    msbuild2.png

Set up the Direct Line Connection

Now that the bot has been created, you will need to setup a Direct Line connection in order to get it to function through Live Assist for Dynamics 365.

  1. On the page that loads after the bot was created, click on the channels button.
    Channels button highlighted
  2. Select the Direct Line icon from the add a channel menu.

    Screen Shot 2017-08-17 at 11.48.24.png

  3. Select the show button next to the first secret key and copy it.  Also ensure you tick the "High Speed Storage" option and hen press the Done button.
    screen_shot_2017-08-17_at_124706.png

Add the bot in Live Assist for Dynamics 365

Once you have a Direct Line key, you can add the bot to LIve Assist for Dynamics 365.

 

  1. Visit the admin portal for the Organization you would like to add the bot for. (This link is different for different organizations - You can find it in the Welcome email you received when setting up Live Assist for Dynamics 365. Once logged in, select Users -> Bots.

    Screen Shot 2017-08-17 at 12.47.54.png
  2. Select Add on the next page

    Screen Shot 2017-08-17 at 12.48.33.png
  3. Give your Bot a name, select the number of licences the bot will use and then paste the Direct Line secret key copied earlier into the Connection Key box. Press Save.

You can specify how many licenses to assign to this bot, with each licence enabling the bot to handle up to three concurrent chats.  The number of licenses option specifies how many licenses a particular bot will use. For example if a bot is configured to take five licenses, it can be involved with up to fifteen chats at any one time. The bot can be involved with chats equalling three times the number of licences it is allocated at any one time. By “involved with” we mean how many chats the bot can be sending and receiving messages in at once. If the bot escalates the chat to a human agent, it is then free to take another chat.

 

You may want to set up particular engagements which your configured bots will answer chats for. You can do this within Engagement portal - you can access this from the Live Assist for Dynamics 365 admin portal under Links -> Engagement Portal.

Testing

You should now have a Bot in Microsoft’s Bot framework which has been added to Live Assist for Dynamics 365. The following steps will tell you how to start a chat which should get answered by your Bot.

NB. In order to properly test the transfer functionality, you need to communicate with the bot via Live Assist (engagement or demo site) and not the azure web chat client channel.


This example assumes that you haven’t got custom engagement settings in place which will stop the chat from being answered by your bot.

If you are testing this on a live system please be aware that the bot will answer any chats that are started. In this case you may want to configure your bot to have a certain skill and set up a new engagement that routes to this skill.
 

  1. Log into Dynamics 365.

  2. Click on the down arrow next to service, select service and then Live Assist Administrator

     

  3. In a new tab the CafeX admin portal should have opened (you may need to allow popups if you can’t see the tab). Click on the Getting Started link at the top right of the page.

  4. On the getting started page that appears, click on the next arrow twice.


     

  5. Then click on the Demo Site button to launch the demo site.


     

  6. On the demo site, click on the Live Chat button to start a chat.

Your bot should answer the chat. You can type messages which the bot will repeat.

 

Next Steps

This walkthrough shows you how to create a basic bot and get it working in Live Assist for Dynamics 365 with the bot agent connector. It can be used as the starting point for a production bot, in which case you will probably want to manage the source code outside of the Azure portal.

If you open your bot in the Azure portal and select build, you should see an option to configure continuous integration. You can follow this guide to manage your source code how you choose.

Screen Shot 2017-08-17 at 12.50.54.png

Microsoft also offer extensive bot framework documentation.

Please see also the Bot Agent Connector API Docs  

Related articles