Microsoft Azure Bot Service

This section describes how you can use Microsoft's Azure Bot Service natural language processing tool in Digital DNA Studio. To use MS Azure Bot Service, you need to build a conversational Bot and deploy it to the Microsoft Azure Cloud. The Digital Person Server connects to your MS Azure Bot to provide conversational content and dynamic data during its interaction with your end-users.

Building your Corpus (MS Azure Bot)

This process is not the same as building a Corpus using Watson or Dialogflow NLPs because you need to build it locally in your machine and then deploy/publish it to the MS Azure Cloud. It also requires some code to implement.

Soul Machines recommends using Microsoft Bot Framework Composer for creating your Bot. Composer is a desktop application for authoring, testing, and managing conversational content and experiences. This visual tool is similar to the Dialogflow console and provides controls that enable you to train your Bot in recognizing intents and their matching responses.

Create your Bot with MS Bot Framework Composer

Download and install the Microsoft Bot Framework Composer Desktop Application. Follow the steps outlined in the Microsoft documentation website:
https://docs.microsoft.com/en-us/composer/install-composer
Use the sample Bot template provided by Soul Machines to create your conversation Bot (corpus).
The template contains two extra intents for setting context variables:
1. SetConversationContext - enables the corpus writer to set their own context variables.
2. SMContextVariables Event received - processes the Soul Machines context variables sent by the SDK (custom Soul Machines functionality).

Notes:

Open the README file that is included in your Bot template to view the recommended steps to create your conversation Bot (corpus).
The Azure Bot Service key, App ID and other account specific details have been removed from the Bot template for security reasons so it won’t work unless you add these to the settings screen—see Publishing from Composer for details. In Composer, you have to go to the settings to configure your Microsoft App ID and enter/create your Azure Bot Service key.

Saving Conversation States

To support getting and setting conversation context properties, there are some changes that need to be made to the Bot logic.

Setting Context Properties

Context properties/variables can be used to save conversation state to be used at a later point in the conversation, e.g. for the card info. The Bot should set context variables in the conversation scope and return the conversation object in responses to share this with the SDK.

For example, to set a component to be shown in a @showcards() function the component needs to be set using the same naming convention as with other conversation providers (prefixed with conversation.public-) and the conversation needs to be returned in the Value field of the response:

MS Composer Set Properties

Receiving and Saving Soul Machines Context Variables

The Soul Machines SDK sends a dialog event named SMContextVariables with a map of context variables in the Value field to the Bot. These variables may be utilized in the Corpus responses (see code snippet below for an example of how to handle this event in the Bot). For more information, please contact your customer support representative.

{
    "$kind": "Microsoft.OnEventActivity",
    "$designer": {
        "id": "7OkzsH",
        "name": "SetSMContextVariables"
    },
    "actions": [
        {
            "$kind": "Microsoft.IfCondition",
            "$designer": {
                "id": "jPFLPr"
            },
            "condition": "=exists(turn.activity.value)",
            "actions": [],
            "elseActions": [
                {
                    "$kind": "Microsoft.EndDialog",
                    "$designer": {
                        "id": "BOiCih"
                    }
                }
            ]
        },
        {
            "$kind": "Microsoft.SetProperty",
            "$designer": {
                "id": "l7AsSb"
            },
            "property": "dialog.tempContextArray",
            "value": "=indicesAndValues(turn.activity.value)"
        },
        {
            "$kind": "Microsoft.Foreach",
            "$designer": {
                "id": "rU9Yvr"
            },
            "index": "dialog.foreach.index",
            "value": "dialog.foreach.value",
            "actions": [
                {
                    "$kind": "Microsoft.SetProperty",
                    "$designer": {
                        "id": "a168CY"
                    },
                    "property": "conversation.${dialog.foreach.value.index}",
                    "value": "${dialog.foreach.value.value}"
                }
            ],
            "itemsProperty": "dialog.tempContextArray"
        }
    ],
    "condition": "=turn.activity.name==\"SMContextVariables\""
}

Building Bot Responses

It is recommended to build the Bot to respond to all possible inputs from the user. For example, if processing an if/else condition based on user input, both the true and false branches should result in a response from the Bot. This ensures that the conversation doesn’t appear to have stalled from the user’s perspective (if the persona does not respond).

Publishing from Composer

Note that there are multiple ways of publishing a Bot, e.g. via command line, using the Azure Portal, etc., the following are two options that are known to work:

Option 1: Create the resources and resource group from Composer

Ensure that you have write access to the subscription before using this option, otherwise, the publish step will fail with an authorization error.

Option 2: Publish to Existing Resources

Create the following resources in Azure Portal:

Web App Bot
Language Understanding - enable both prediction and authoring

In the “Bot management and configurations” tab of Composer, fill out the App ID/Password and Azure Bot Service fields with the keys/endpoints/names copied from the Azure Portal.

Create a publish profile that includes the fields hostname and luisResource - these don’t get added automatically and need to be added by toggling the “Advanced Settings View (json)” or by manually editing the appsettings.json file in the “settings” folder.

Obtaining Your Azure Bot Secret Keys

To configure your Digital Person in DDNA Studio, enter the Microsoft Bot Direct Line API 3.0 secret key in the Azure Bot Service NLP secret key field. Two of these keys are found under Settings > Channels > Direct Line in the Web App Bot resource of the Azure Portal (see screenshots below).

Connect Channels - Direct Line

The MS Azure Bot Secret Keys must be entered in Digital DNA Studio when you have selected to use the MS Azure Bot Service NLP for the conversation platform in your Digital Person project. Two keys are available and either one of them can be used.

The Secret Key is used to access the MS Azure Bot which enables the Soul Machines SDK to make or send requests to the MS Azure Bot.

Useful Links

Initial creation of Bot/Azure Bot Service resources: Publish a bot to Azure - Bot Composer
To format Bot responses: .lg file format - Bot Service
To obtain Azure Bot key for use in Soul file: Authentication - Bot Service

Contents

1 Building your Corpus (MS Azure Bot)
2 Obtaining Your Azure Bot Secret Keys
3 Useful Links