Aura –

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

auraCommand model

Description of the auraCommand model suitable for sending intents directly to Aura with no recognition stage

Introduction

An auraCommand is an structure to send intents directly to Aura. It includes specific messages consisting on pre-defined options that the user can select from Aura’s interface as part of the response to her request. These messages come from channels using Direct Line format. Currently, they correspond to notifications and suggestions.

The aura-bot recognizer in charge of auraCommand is aura-command-recognizer-middleware. This recognizer detects if the message matches auraCommand format and then processes the message and extract the intent and entities from it.

An auraCommand should be sent within the channelData of the request to aura-bot in an optional property called auraCommand.

AuraCommand property in channelData

It is the channelData property called AuraCommand, which value should fit an AuraCommand Model.

Property	Type	Description
auraCommand	AuraCommand	This property contains an `auraCommand` object.

AuraCommand Model

Property	Type	Description
type	string	`AuraCommand` type: suggestion: used to send a common intent. The prefix of the intent must be `intent.`. Its the type by default. operation: It represents an intent that needs a context in Aura. The prefix of the intent must be `operation`. notification: It represents an intent generated by notification. The prefix must be `intent`. text: The value of the `auraCommand` contains directly a `string` with the text to be recognized by NLP. event: The value of the AuraCommand contains and event that aura-bot recognizes to carry out an action.
value	Intent model or string	Object intent or text.
utm	Utm model	Source that contains the AuraCommand.
actions	Action model	Array of actions.

Intent model

Property	Type	Description
intent	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add the it.
entities	Entity model	Array with the entities. This array can be empty.

Entity model

Property	Type	Description
type	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add it.
entity	string	Name of the entity. If this name does not contain the prefix `ent.` Aura will add it.
canon	string
score	float	Array with the entities. This array can be empty.

Utm model

Property	Type	Description
source	string	It identifies which site sent the traffic. In Aura, use the channel name.
medium	string	It identifies what type of link was used, such as cost per click or email. In Aura, use banner, button, etc.
campaign	string	It identifies a specific product, promotion or strategic campaign.
term	string	It identifies search terms.
content	string	It identifies what was specifically clicked to bring the user to the site, such as a banner ad or a text link.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

dialogContext model

Description of the dialogContext model, for the management of different existing options in the response

Introduction

A dialogContext is a structure that facilitates the recognition of CardActions and prompts without the need of training.

It has the following characteristics:

It can be autogenerated when a prompt is active.
It can be autogenerated when there is a CardAction.
It can be created manually in a dialog but with certain restrictions.
It is stored in the conversation cache.
It is processed by the dialog-context-recognizer-middleware.
It is auto-generated and stored by the aura-bot adapter.
It can be configured at channel level, prompt level and CardAction level.
It facilitates the recognition of CardActions if a user, instead of pressing the button, types the button text.
It facilitates the recognition of numbered lists either by ordinals or cardinals.
It uses a proximity search algorithm.
It solves the problems of the recognition of numbers and ordinals that the current Bot Framework prompt has.

Existing models

dialogContext model

Property	Type	Description
text	String	Text or texts (separated by ‘\|’) with the options to be matched.
value	Object	Object of `IntentResult` or other with the action to carry out if the option is validated.

Example:

"dialogContext": [
                    {
                        "text": "Hello",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "greetings",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    },
                    {
                        "text": "Bye bye mi picolissima dama",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "goodbyes",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    }
                ]

Channel model

The dialogContext model at the channel level applies to all dialog components.

This model has the highest priority, i.e., in case of conflict between models, the channel model has the highest weight.

This model is inside the responseOptions.dialogContext property. Check it in Aura channel model: ResponseOptions model.

An example is shown below:


channel: {
...
        responseOptions: {
            dialogContext: {
                normalizeTerms: true,
                disabled: false,
                disabledMerge: false,
                processFromClient: false,
                returnToClient: false,
                defaultListType: 'none',
                promptChoice: {
                    generate: 'never',
                    generateList: false
                },
                cardActions: {
                    generate: 'never',
                    generateList: false
                }
            }
        }
    },
...

Prompt model

The options of dialogContext for a prompt can be included inside the property validations of Prompt Options within its sub-property dialogContext.

When generating the list of options, the system takes into account two properties of the prompt: recognizeNumbers and recognizeOrdinals.

In these cases:

If the prompt has recognizeNumbers=false and we have activated the list of options, only the ordinal values of each option will be generated.
If the option recognizeOrdinals=false, then only the cardinal options will be generated.
If both are set to false, no list items will be generated.

By default, the prompt has both properties set to true.

Property	Type	Description
originalFindChoicesOptions	Object	Original prompt findChoiceOptions. Used if the dialogContext recognizer needs to change it, the prompt would be restored to the original state.
originalStored	Boolean	It indicates whether the dialogContext recognizer had to overwrite the original prompt values. Default: `false`.
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for prompt options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of list to enumerate the prompt options. Default: `OrdinalCardinal`.

Example of prompt options:


{
  "Choices": [
    {
      "value": "Lunes",
      "synonyms": [
        "El lunes"
      ]
    },
    {
      "value": "martes"
    }
  ],
  "validations": {
    "dialogContext": {
      "enabled": true,
      "listType": "ordinal "
    }
  }
}

CardAction model

The options of dialogContext for a CardAction can be included inside the property channelData of button options, within the sub-property dialogContext.

Property	Type	Description
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for CardAction options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of the list to enumerate the CardAction buttons. Default: `OrdinalCardinal`.
synonyms	String[]	Array of strings with synonyms of the title.

{
  "buttons": [
    {
      "type": "postBack",
      "title": "Monday",
      "value": {
        "intent": "monday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal"
        }
      }
    },
    {
      "type": "postBack",
      "title": "Wednesday",
      "value": {
        "intent": "wednesday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal",
          "synonyms": [
            "X"
          ]
        }
      }
    }
  ]
}

Custom dialogContext

It is possible to add in the channelData a dialogContext manually. If the channel configuration allows it, this will be merged with the _dialogContext that is generated automatically.

The following rules must be taken into account when including our own dialogContext:

Do not generate the list values, that is, do not add ordinals and/or cardinals, as this will be done by the system.
The options of a custom dialogContext are included right at the top of the list.

How does dialogContext work?

The dialogContext flowchart includes two differentiate phases: recognition phase and build phase, described below.

Recognition phase

When validating if the user has entered a phrase that matches the dialogContext that we have generated from the previous answer, take into account that the comparison is done by proximity.

The match value will be reported in a score field that goes from 0 to 1. Valid values will be those that are greater or equal to a given threshold. For a dialogContext we have two thresholds.

AURA_DIALOG_CONTEXT_THRESHOLD: Default threshold when comparing two strings. Default value: 0.80.
AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD: Threshold used in case dialogContext elements are in list form and also if the input phrase includes a number. By default, 0.95.
This value is so high because if the user writes ‘11’ or ’the 11’, and there are only 5 elements in the list, the comparison could give us a very high value, since comparing 11 with 1 has a threshold higher than 0.80, which means that writing 11 would select the first option. To avoid this kind of cases when there are numbers in the user input and the list is enumerated, then the threshold should be stricter.

Another thing to take into account is that if the dialogContext does not get a valid match, if we have an active prompt choice, the system will override its recognizeNumbers and recognizeOrdinals properties, as long as we are working with enumerated elements.

This is done because when MS Bot Framework detects an ordinal number in a sentence, it ignores the rest of the sentence, which can lead to many errors. These values are restored every time the prompt is regenerated if it has not been resolved.

In the recognition phase, the dialogContext recognizer compares value to value, and in the case that one of them meets the conditions, the intention associated with the value is established. It also assigns to the input text the value expected by the prompt, in case there is one.

Example:

DialogContext

[
  {
    "text": "1|the 1|one|the one|first|the first|Monday",
    "value": {
      "intent": "monday"
    }
  },
  {
    "text": "2|the 2|two|the two|second|the second|Tuesday",
    "value": {
      "intent": "tuesday"
    }
  },
  {
    "text": "3|the 3|three|the three|third|the third|X|Wednesday",
    "value": {
      "intent": "wednesday"
    }
  },
  {
    "text": "4|the 4|four|the four|fourth|the fourth|Thursday",
    "value": "The Thursday"
  },
  {
    "text": "5|the 5|five|the five|fifth|the fifth|Friday",
    "value": "Friday"
  }
]

User Input: the 4

In this case, as the list is numbered and the user has entered a number in his sentence, the selected threshold will be AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD.
The elements of each option will be compared with the user’s value:

   1 ≅ the 4  -> Score 0 
   the 1 ≅ the 4  -> Score 0.80
   ......
   the 4 ≅ the 4  -> Score 1.0   -> Option Selected

If the selected option has value, the value is assigned to the activity text. In other case, the assigned value is the last value of the text, in this case ‘Thursday’.
If there is a prompt choice, the validations recognizeNumbers and recognizeOrdinals are set to false.

Build phase

The build phase is responsible for collecting the customized dialogContext (if any) and, in turn, for generating the dialogContext of the CardActions and Prompt in the different activities that make up the output message.

The enumeration of the elements depends on the configuration of the channel and the respective components. Once generated, it is stored in the user’s conversation cache.

The module in charge of this procedure is the Aura Bot Adapter.