Aura – development

Docs:

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

Aura NLP Adapters

What are Aura NLP adapters

Adapters are used in order to modify the response achieved by the rest of the pipeline stages.

The different types of adapters are included in the following sections.

Description

The specific intent recognition stage (CLU, Exact match, Grammars, etc.) recognizes the user’s intent.
Aura NLP will provide as an output a recognized intent and an entity ID.

Path

Files

Keys: intent
Value: the value for each key corresponds to an ID from different sources.

An example is shown below. Each intent is mapped with a specific ID.

```typescript
{
"intent.exact-match.faq.1": "1",
"intent.exact-match.faq.2": "2",
"intent.exact-match.faq.3": "3"
}
```

Afterwards, aura-bot will receive the recognized intent and the entity ID as an output from the NLP stage.

Review that all the included IDs in this file are existing in the corresponding sources and the matching between the intents and entities for this ID.
Review that the intent name is previously defined.
Include the intents in alphabetical order.
It is recommended to include in the E2E tests phrases to validate that the mapping is correctly done.

Configuration

This stage requires the following configuration in the nlp.json configuration file, in which the field intent_template should point to the use case intent.

As an example, if Exact match is the intent recognizer stage, it can be:

        "intent_template":"intent.exact-match.faq"
        }

Intent Entity Mapper

Description

It can be used in:

Personalized experiences to configure a particular entity based on a specific intent.

In both scenarios:

An intent recognition stage (CLU, Exact match, Grammars, etc.) recognizes the user’s intent.
Intent Entity Mapper adapter is trained to map the intent with an entity name and label.
Aura NLP provides as an output the recognized intent and entity.

Path

auracog_pipelines.stage_wrappers.adapter_wrapper.intent_entity_mapper_wrapper.IntentEntityMapperWrapper

Files

This stage requires an intent_entity_mapper.json file. It maps a specific intent with an entity name and label:

The keys are the intent names.
Values for each key contain another key-value pair:
- entity_name (mandatory): The name of the new entity.
- entity_label (optional): The label of the new entity. If not provided, it uses the label defined in the nlp.json configuration file.

An example is shown below:

{
    "intent.exact-match.faq.1": {
        "entity_name": "1",
    },
    "intent.exact-match.faq.2": {
        "entity_name": "2",
        "entity_label": "test-label" 
    },
    "intent.exact-match.faq.3": {
        "entity_name": "3"
    }
}

Afterwards, aura-bot will receive the recognized intent and the entity name as an output from the NLP stage.

Best practices to edit `intent_entity_mapper.json`

Review that all the included entity names in this file exist in the corresponding sources.
Review the matching between the intents and entities.
Review that the intent name is previously defined.
Include the intents in alphabetical order.
It is also recommended to include it in the E2E test phrases to validate whether the mapping is correctly done.

Configuration

This stage requires the following settings in the nlp.json configuration file, under the intent_entity_mapper key:

intent_template (mandatory): The intent name to replace the original intent.
entity_label_template (optional, default None): A default label name for the entities not defined in the intent_entity_mapper.json file.
entity_type_template (optional, default faq): The type of the new entities.
1. The OpenaiEmbeddingsRecognizer stage is included in the same pipeline.

Here is an example:

"intent_entity_mapper": {
    "intent_template": "intent.tv.search",
    "entity_label_template": "REAL MADRID",
    "entity_type_template": "ent.audiovisual_sports_team",
}

None Handler

Description

None Handler is a stage used when the intent recognized by the pipeline stages is None. It modifies the None intent by the intent predefined in the file none_mapper.json for the specific domain. You can select any intent defined in the system to be pointed in this adapter.

Path

auracog_pipelines.stage_wrappers.adapter_wrapper.none_handler_wrapper.NoneHandlerWrapper

Files

None Handler requires one file: none_mapper.json that indicates, within a specific domain, which intent must be set if the recognized intent is None. Therefore, if the domain is already defined and the system recognizes the intent None, then the intent is replaced by the value indicated in the file.

In this file:

Keys: different domains
Values: value for each key is the intent mapped with this domain.

Developers can select any intent defined in the system to be pointed in this adapter.

An example is shown below:

{
  "domain.tv_content": "intent.tv.none",
  "domain.tv_desco": "intent.tv.none",
  "domain.tv_record": "intent.tv.none",
  "domain.tv_wh3": "intent.tv.none"
}

In the example, if the domain is domain.tv_content and the system recognizes the intent None, then this intent is replaced by intent.tv.none.

Configuration

This stage does not require any configuration.

Standard Threshold

Description

Standard Threshold allows the establishment of a threshold for the scores provided by preceding pipeline stages. If the score obtained by the previous stages is lower than the established threshold, the Standard Threshold provides score 0 and the intent is replaced by the default value set in the configuration.

This stage is useful to prevent false positives and can be included in any place of the pipeline. The NLP Global Team recommends to set this threshold to 0.6.

Path

auracog_pipelines.stage_wrappers.adapter_wrapper.standard_threshold_wrapper.StandardThresholdWrapper

Files

Standard Threshold does not require any file.

Configuration

This stage requires the following configuration in the nlp.json file, depending on the language and the channel:

{
  "es-es": {
    "mp": {
      "threshold": {
         "default": {
           "threshold": 0.1,
           "intent": "intent.default" 
        },
         "intent.test": {
            "threshold": 0.8,
            "intent": "None" 
        }
      } 
    }     
  }

The fields are explained below:

threshold: value between 0 and 1 indicating the limit that triggers the action of the adapter.
- This field can be defined per intent, thus having a different threshold for each intent.
- The default intent must be always specified and, additionally, you can define a different threshold for other specific intent in order to improve the recognition process.
- The NLP Global Team recommends to set this threshold to 0.6.
intent: this field contains an internal string identifier, that is associated if the score value is lower than the threshold.

In the previous example, the default config applies to every intent, with accuracy 0.1 and intent intent.default. But, specifically for the intent intent.test, the applied configuration has accuracy 0.8 and the associated intent is None.

Entity Tagger Adapter

Description

Entity Tagger Adapter is a stage that allows entities tagging through the definition of aliases and labels on them.

Path

auracog_pipelines.stage_wrappers.adapter_wrapper.entity_tagger_adapter_wrapper.EntityTaggerAdapterWrapper

Files

The Entity Tagger Adapter stage requires four files:

sdict_items: Items dictionary including the canonical values of entities.
sdict_aliases: Alias dictionary including the aliases for an entity.
ner_entity_translation.json
ner_aliases.json

ner_entity_translation.json

ner_entity_translation.json indicates, for each entity type, if canon and label have been defined for the entity type or not.

It is a JSON file that must be generated manually to define properties for each entity type.

The keys are entity types.
Values for each key contain another key-value pair:
- Keys: canon and label
- Values: boolean operators (true/false) depending on whether a canon and/or label has been defined for a given entity type or not.

An example of ner_entity_translation is shown below:

{
  "DEFAULT": {
    "canon": false,
    "label": false
  },
  " ent.audiovisual_actor ": {
    "canon": true,
    "label": false
  }
}

Where default represents the default value if the entity type is not included in the dictionary. The default field is not mandatory if all the entity types are defined in the file.

When a new entity is added, it must be included in the ner_entity_translation.json file with the expected behavior for the canon and label. Likewise, if the behavior for canon and label of an entity changes, it is required to update this file.

As best practices, entities should be ordered alphabetically.

ner_aliases.json

ner_aliases.json is an optional file required if you need to match/map the canon value to some other value requested by an API or search engine (currently, it is used by Spain to search content in the M+ database).

It is a JSON dictionary that must be generated manually, where:

Keys: entity types.
The value of each key includes another key-value pair:
- Keys: labels
- Value for each key: list of values contemplating just the canonical form(s) of the entity label

When adding a new entity, in case the entity should have a label, the label has to be assigned to the canons that we want to be identified by this label.

An example of ner_aliases dictionary is shown below:

{
    "ent.audiovisual_genre": {
        "CN": [
            "movies",
            "films"
        ],
        "CT": [
            "shorts",
            "short film"
        ]
    },
}

The following example shows the mapping between alias-canon-label and their corresponding files:

   docu (`sdict_aliases`) -> documentary (`sdict_items`)-> DC  (`ner_aliases`)

Best practices for the edition of ner_aliases.json

Canon names should be expressed as in sdict_items.json, including capitalization, diacritic marks and punctuation.
Entities should be ordered alphabetically.
Labels inside entities should be ordered alphabetically.

Configuration

No configuration is required.

Description

If the disambiguation process cannot discern between multiple entities, then the intent returned by Aura NLP to the bot will be a disambiguation intent as a top intent at first level. In this intent, each option is composed of the original top intent and one entity per option. These options will be presented to the user for him to choose the most appropriate one.

The input for this stage includes: a list of intents; 1 top intent (intent recognized with the higher score); a list of entities.
The output from this stage includes: the top intent and different options (options in the data model) of recognized entities.

Here is an example of the input and output data models for the disambiguation by entities stage, where entities are IDs.

Input data model:

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [
            {
                'entity': '14', 'type': 'faq', 'score': 0.90, 'start_index': 1, 'end_index': 1, 'canon': '14', 'label': null
            },
            {
                'entity': '16', 'type': 'faq', 'score': 0.88, 'start_index': 1, 'end_index': 1, 'canon': '16', 'label': null
            },
            {
                'entity': '12', 'type': 'faq', 'score': 0.60, 'start_index': 1, 'end_index': 1, 'canon': '12', 'label': null
            }
        ],
        'intents': [
        ]
    },
    'domain_result': {}
}

Output data model:


    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [],
        'top_result': {'intent': 'intent.disambiguation', 'score': 1.0},
        'intents': [
            {'intent': 'intent.disambiguation', 'score': 1.0}
        ]
    },
    'domain_result': {},
    'options': [
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': '14', 'type': 'faq', 'score': 0.90, 'start_index': 1, 'end_index': 1, 'canon': '14', 'label': null
                    }
                ],
                'intents': [
                ]
            }
            'domain_result': {},
            'options': []
        },
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': '16', 'type': 'faq', 'score': 0.88, 'start_index': 1, 'end_index': 1, 'canon': '16', 'label': null
                    }
                ],
                'intents': [
                ]
            },
            'domain_result': {},
            'options': []
        }
    ]
},

Path

Files

Configuration

This stage requires the following configuration in the nlp.json file depending on the language and the channel:

{
  "es-es": {
    "mp": {
        "disambiguation_margin": 0.2,
        "exact_match": 0.92,
        "intent_template": "intent.disambiguation",
      } 
    }     
  }
}

The fields determine how the disambiguation process is carried out:

intent_template: This field contains an internal string identifier corresponding to the intent resulting from this stage if no disambiguation can be carried out.
exact_match: value between 0 and 1. This value is used to check if any recognized entity score is above this value.
disambiguation_margin: value between 0 and 1 used to set an interval.

The combination of these two last parameters provides different scenarios:

The score of certain entities is equal or higher than exact_match (left graphic).
- Only the entity with the best score is considered.
- In case of tie (more than one entity with the highest score), all of them are returned.
The score of all entities is below the exact_match (right graphic). Only those entities whose score is in the interval: ([top score], [top score - disambiguation_margin]) (both included) are considered.

Intent Disambiguation Adapter

Description

The goal of this stage is to disambiguate when, in an utterance, several intents are recognized.

If the disambiguation process cannot discern between multiple intents, then the intent returned by this stage will be a disambiguation intent as a top intent at first level. In this intent, each option is composed of one intent (that fulfils the conditions to be disambiguated) and a list of entities. These options will be presented to the user to choose the most appropriate one.

The general behavior of this stage is explained below:

The input for this stage includes: a list of intents and a list of entities.
The output for this stage includes: the different options for intents recognized during the disambiguation (options in the data model) and the original list of entities.

However, if black lists are defined, the behavior is explained in the following sub-section.

Intent disambiguation with a blacklist of intents

Aura NLP allows the integration of configurable blacklists of intents for a custom behavior of disambiguation. In this case, the disambiguation mechanisms will not apply for the intents included in the blacklist. The use case constructors can edit a blacklist of intents in the nlp.json configuration file, filling the parameter intent_blacklist.

When there is a blacklist of intents, the disambiguation process behaves as explained below:

a. If the top scored intent is included in the intent_blacklist, the pipeline will return this unique intent (no disambiguation is launched).

b. If the top scored intent is not included in the intent_blacklist, then the predefined values of the configuration parameters come into play:

If the score of the top scored intent is higher than exact_match, then this intent is returned. In case of tie (more than one intent with the highest score), all of them are returned.
If the score of the top scored intent is lower than exact_match, then all the intents whose score is in the interval between the top score and the disambiguation_margin and are not in the intent_blacklist are returned.
In this case, the final intent will be the one described in intent_template (with a score of 1.0) and the selected intents will be placed in the options of the result.

Path

auracog_pipelines.stage_wrappers.adapter_wrapper.intent_disambiguation_wrapper.IntentDisambiguationAdapterWrapper

Files

No files are required.

Configuration

This stage requires the following configuration in the nlp.json file for each country and channel, within the key intent_disambiguation.

The following parameters are required for this stage:

exact_match: Float number, value between 0 and 1. If the intent with the highest score is greater than this value, the result is this intent (if this intent is not included in the intent_blacklist).
disambiguation_margin: Float number. Margin between the highest score and the lower score considered for the response.
intent_template: String. Name of the intent that the stage returns when there are multiple options as response.
intent_blacklist: List of intents for which the disambiguation mechanisms will not apply. This parameter is mandatory. If there are no blacklisted intents, it will have to be an empty list.
⚠️ none intent must always be included in the blacklist, as it is not going to be offered as an option to disambiguate.

See an example of nlp.json file configuration for this stage:

{
  "es-es": {
    "mp": {
      "intent_disambiguation": {
         "disambiguation_margin": 0.2,
         "exact_match": 0.92,
         "intent_template": "intent.disambiguation",
         "intent_blacklist": ["intent.blacklisted_intent1", "intent.blacklisted_intent2"]
      },
      ...
    }
  }
}

Examples of intent disambiguation adapter

Basic example for intent disambiguation adapter inclusion in a pipeline

{
  "name": "IntentDisambiguationExample",
  "initial_node_id": "IntentDisambiguationExamplePipeline",
  "elements": {
    "IntentDisambiguationExamplePipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
    "RecognizerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.recognizer_wrapper"
    },
    "IntentDisambiguationAdapterWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.intent_disambiguation_wrapper.IntentDisambiguationAdapterWrapper"
    }
  },
  "links": {
    "IntentDisambiguationExamplePipeline": [
      "RecognizerWrapper",
      "IntentDisambiguationAdapterWrapper"
    ]
  }
}

General behavior of intent disambiguation stage (with no blacklist of intents)

Here is an example of the input and output data models for the intent disambiguation stage, belonging to the OpenAI embeddings stage, where the disambiguation margin is 0.2:

Input data model

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [
            {
                'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1,         'end_index': 2, 'canon': 'canon1', 'label': 'label1'
            },
            {
                'entity': 'name2', 'type': 'type2', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label2'
            }
        ],
        'top_result': {'intent': 'intent.tv.search', 'score': 0.96},
        'intents': [
            {'intent': 'intent.tv.search', 'score': 0.96},
            {'intent': 'intent.tv.display', 'score': 0.90},
            {'intent': 'intent.tv.launch', 'score': 0.60}
        ]
    },
    'domain_result': {}
}

Output data model (2 intents fulfil the predefined criteria)

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [],
        'top_result': {'intent': 'intent.disambiguation', 'score': 1.0},
        'intents': [
            {'intent': 'intent.disambiguation', 'score': 1.0}
        ]
    },
    'domain_result': {},
    'options': [
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
                    },
                    {
                        'entity': 'name2', 'type': 'type2', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label2'
                    }
                ],
                'top_result': {'intent': 'intent.tv.search', 'score': 0.96},
                'intents': [
                    {'intent': 'intent.tv.search', 'score': 0.96}
                ]
            },
            'domain_result': {},
            'options': []
        },
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
                    },
                    {
                        'entity': 'name2', 'type': 'type2', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label2'
                    }
                ],
                'top_result': {'intent': 'intent.tv.display', 'score': 0.90},
                'intents': [
                    {'intent': 'intent.tv.display', 'score': 0.90}
                ]
            },
            'domain_result': {},
            'options': []
        }
    ]
}

Behavior of intent disambiguation stage with a blacklist of intents.
Scenario 1: top intent is included in the blacklist

Input data model

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [
            {
                'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
            }
        ],
        'top_result': {'intent': 'intent.common.greetings', 'score': 0.96},
        'intents': [
            {'intent': 'intent.common.greetings', 'score': 0.96},
            {'intent': 'intent.tv.display', 'score': 0.90},
            {'intent': 'None', 'score': 0.60}
        ]
    },
    'domain_result': {}
}

Output data model: the top intent is included in the blacklist, therefore, no disambiguation is launched.

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [
            {
                'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
            }
        ],
        'top_result': {'intent': 'intent.common.greetings', 'score': 0.96},
        'intents': [
            {'intent': 'intent.common.greetings', 'score': 0.96},
            {'intent': 'intent.tv.display', 'score': 0.90},
            {'intent': 'None', 'score': 0.60}
        ]
    },
    'domain_result': {}
}

Behavior of intent disambiguation stage with a blacklist of intents
Scenario 2: top intent is included in the blacklist

Input data model

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [
            {
                'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
            }
        ],
        'top_result': {'intent': 'intent.tv.search', 'score': 0.96},
        'intents': [
            {'intent': 'intent.tv.search', 'score': 0.96},
            {'intent': 'None', 'score': 0.90}
            {'intent': 'intent.tv.display', 'score': 0.89}
        ]
    },
    'domain_result': {}
}

Output data model: the top intent is not included in the blacklist and more than one intent fulfil the condition for disambiguation » The options in the blacklist are ignored and the remaining intents are disambiguated.

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [],
        'top_result': {'intent': 'intent.disambiguation', 'score': 1.0},
        'intents': [
            {'intent': 'intent.disambiguation', 'score': 1.0}
        ]
    },
    'domain_result': {},
    'options': [
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
                    }
                ],
                'top_result': {'intent': 'intent.tv.search', 'score': 0.96},
                'intents': [
                    {'intent': 'intent.tv.search', 'score': 0.96}
                ]
            },
            'domain_result': {},
            'options': []
        },
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
                    }
                ],
                'top_result': {'intent': 'intent.tv.display', 'score': 0.89},
                'intents': [
                    {'intent': 'intent.tv.display', 'score': 0.89}
                ]
            },
            'domain_result': {},
            'options': []
        }
    ]
}

Length Adapter

Description

The objective of this stage is to control the maximum and minimum length of a phrase in order to avoid it to be too short or too long. The maximum/minimum number of characters is configurable. The stage discards the out-of-range phrases, as they are not recognized properly by Aura NLP, thus saving time and resources in the recognition process.

The Length Adapter returns a configurable intent template if the length of the received phrase in the pipeline message is higher than the maximum number of configurable characters or lower than the minimum one. The intent template is also configurable.

Path

auracog_pipelines.stage_wrappers.adapter_wrapper.lenght_adapter_wrapper.LenghtAdapterWrapper

Files

No files required.

Configuration

This stage requires a specific configuration in the pipeline configuration file pipeline.json, within the args section of this file, that contains the following fields:

max: maximum number of characters in the phrase of the received pipeline message.
min: minimum number of characters in the phrase of the received pipeline message.
intent_template: intent name to be returned if the number of characters is lower than the min value or higher than max value.

      "args": {
         "max": 50,
         "min": 1,
         "intent_template": "intent.example"
      }

You can also configure more than one stage of the Length Adapter to return different intents for max or min length characters.

Docs:

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

Aura Minibot user guide

Guidelines for the installation and configuration of Aura minibot

⚠️ In Aura’s new architecture, Aura minibot works jointly with Aura minigroot

Introduction to Aura minibot

Aura minibot is a tool intended for testing purposes in local environment.

It is highly recommended to use Aura minibot to get familiar with aura-bot when developing use cases.

Pre-requirements

Azure accounts (It can be a free one)
Visual Studio Code (required for the minibot generated by a Docker image)
Remote – Containers extension for Visual Studio Code (required for the minibot generated by a Docker image)
Aura docker registry token (Contact your manager or APE team who will supply it for you)

Register a bot in Azure

The current section explains the steps for the registration of a bot in Azure. Bear in mind that the Azure site and the steps to register a new resource change very often. If any questions arise, please contact APE Team, so they can aid with the registration.

In the Azure portal, create a resource of Azure Bot type.
Type in the search box “bot” and click on “Azure Bot”, the click on “Create”.
Fill in the form fields with the following values:
- Bot handle: unique identifier for your bot, for instance: aura-bot-ape
- Subscription: OB Subscription
- Resource Group: OB Resource Group
- Pricing tier: Free
- Type of App: Multi Tenant
- Creation type: Create new Microsoft App ID
Now click on “Review + create”

⚠️ Currently, with the addition of the aura-groot, it is needed to create 2 bots in Azure (root & skill).

The new Azure Bot resource will be validated, so the next step is to click on “Create” again, so this step will deploy our new resource. A new Microsoft App Id and password will be generated.
Click on “Go to Resource” to see the breakdown of options and configurations available for your bot.
Once the Azure Bot is created, it is required to get two parameters: Microsoft App ID and Microsoft App Password:
- Microsoft App ID is located in Configuration. Copy it in a safe place.
- Get Microsoft App Password by clicking on “Manage”.
- Copy it in a safe place, as you will need it for the bot identification and cannot be visualized afterwards, when requesting a token.
- In case you have lost it, click on “New client secret” and set the expiration date.

Install and configure Aura minibot

The minibot is provided as a Docker image from Aura’s private registry.

From this docker image, follow the next steps for its installation and configuration.

Complementary, the minibot can also be generated through a .tgz file, if the docker cannot be used.

Set all the required environment variables

Firstly, you need to set some environment variables located in:

aura-mini-bot/config.env

In this file, there are the environment variables shared between aura-groot and aura-bot as skill. Also, there are variables for the scripts to set Direct Line endpoint, so in Microsoft variables you should set the ones of the Azure bot that will be configured in aura-groot.

You also have two files with variables for aura-groot and aura-bot as skill. These files are:

aura-mini-bot/config-groot.env
aura-mini-bot/config-bot.env

Bot credentials

Edit the following variables using the values you have in Azure portal for aura-groot and aura-bot:

AURA_MICROSOFT_APP_PASSWORD=<generated secret>
AURA_MICROSOFT_APP_ID=<Microsoft App Id>

As now we have 2 bots, you should set these variables in both files, config-groot.env and config-bot.env. Also, you should set the same AURA_MICROSOFT_APP_ID that you set in config-bot.env in the mocked skills configuration file (mock-configuration/mocks/mock-files/skills-configuration-mock.json), in the appId field, to indicate aura-groot the appId of the skill it has to communicate with.

Access to the database

Minibot requires access to a MongoDB database to be able to store information related to the user session. Those variables can be found here:

AURA_MONGODB_BOT_DATABASE=aura-minibot
AURA_MONGODB_PASSWORD=pass
AURA_MONGODB_URI=mongodb://localhost:27017?authSource=admin
AURA_MONGODB_USERNAME=admin

By default, AURA_MONGODB_USERNAME and AURA_MONGODB_PASSWORD variables are set as “admin” and “pass” in the .env file. These values must match the <user_name> and <password_db> set in the next step.

Run a local database

If you do not have any mongoDB instance, download a Docker image and run docker for storing sessions locally:

docker pull mongo:4.4
docker run -d -p 27017-27019:27017-27019 --name mongodb mongo:4.4

The steps to modify the DB with the default user and password for the minibot are included here as an example, sorted by execution order:

Enter the docker container:
```
docker exec -it mongodb bash
```
Enter in Mongo shell
```
mongo
```

Create the user in admin DB

use admin
db.createUser({user:"<user_name>", pwd: "<password_db>", roles: [{role:"userAdmin", db:"admin"}]})

Create the aura-bot-es-dev DB
```
use aura-bot-es-dev
```
Exit MongoDB console
```
exit
```
Exit docker container
```
exit
```

Run Aura minibot on docker

Minibot is provided as a docker image from a private registry.

To access the private registry, request access to Aura Global (through the APE Team) and set login credentials on docker:

Get registry access

Use the following command:

docker login -u <user-id> -p <user-token> auraregistry.azurecr.io

With azcli:

az login
az acr login --name auraregistry

Pull minibot and minigroot images

Get the minigroot and minibot as skill specific images:

docker pull auraregistry.azurecr.io/aura/aura-mini-groot:<version>
docker pull auraregistry.azurecr.io/aura/aura-mini-bot:<version>

Get all available versions from registry

It is possible to get all available minibot and minigroot images using azcli (native or dockerized version) tool and following these steps:

Login in Azure:
```
az login
```
This message will appear: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXX to authenticate.
Open the URI an insert the provided code.
To get the available minibot images from registry, the user must use this command.
```
az acr repository show-tags -n auraregistry --repository aura/aura-mini-bot
```
To get the available minigroot images from registry, the user must use this command.
```
az acr repository show-tags -n auraregistry --repository aura/aura-mini-groot
```
These commands will show an array of string with all available versions for each.

Get latest version

To get the latest minigroot and minibot versions, replace <version> by latest in the command of the section Pull minibot and minigroot images.

NOTE: using latest for the second or successive times does not update the image if there is a new latest image in the registry. In this scenario, to make sure the latest image is being retrieved and pulled, execute the following docker commands in that order:

docker compose stop

docker-compose rm -f

docker-compose pull

docker-compose up -d

Launch minibot

To work with the all-in-one solution, five files must be created: docker-compose.yml, config.env, config-groot.env, config-bot.env and ngrok.yml.

The initial scaffolding is located in the repo: https://github.com/Telefonica/aura-mini-bot (Contact your manager or APE team if you do not have access to it) In this case, you can use the command:

docker compose up -d

Example of docker-compose.yml file

version: '3'

services:
  mongodb:
    image: mongo:4.2
    restart: unless-stopped
    env_file:
      - config.env
    ports:
      - "27017:27017"

  aura-minigroot:
    image: auraregistry.azurecr.io/aura/aura-mini-groot:<version>
    volumes:
      - ./mock-configuration/mocks/mock-files/skills-configuration-mock.json:/opt/aura-groot/aura-mini-groot/sources/files/mock-files/skills-configuration-mock.json
    env_file:
      - config.env
      - congif-groot.env
    restart: unless-stopped
    depends_on:
      - mongodb
    ports:
      - "8080:8080"

  aura-minibot:
    image: auraregistry.azurecr.io/aura/aura-mini-bot:<version>
    volumes:
      - ./packages:/tmp/dialogs
      - ./mock-configuration:/opt/aura-bot/aura-mini-bot/mock-configuration
    env_file:
      - config.env
      - config-bot.env
    restart: unless-stopped
    depends_on:
      - mongodb
    ports:
      - "8081:8081" 

  azcli:
    image: mcr.microsoft.com/azure-cli:2.49.0
    depends_on:
      - ngrok
    env_file:
      - config.env
    command: >
      sh -c "
        az login --tenant $$AURA_MICROSOFT_TENANT &&
        az account set --subscription $$AURA_MICROSOFT_SUBSCRIPTION &&
        az bot update -n $$AURA_MICROSOFT_BOT_NAME -g $$AURA_MICROSOFT_RESOURCE_GROUP --endpoint $$(curl --silent http://ngrok:4040/api/tunnels | jq -r '.tunnels | map(.public_url) | .[]' | grep https)/api/messages
      "      
  ngrok:
    image: ngrok/ngrok
    command:
      - "start"
      - "--all"
      - "--config"
      - "/etc/ngrok.yml"
    volumes:
      - ./ngrok.yml:/etc/ngrok.yml
    ports:
      - "4040:4040"

Example of config.env file

# Microsoft Azure
AURA_MICROSOFT_BOT_NAME=<your-aura-bot-name>
AURA_MICROSOFT_RESOURCE_GROUP=<your-azure-resource-group>
AURA_MICROSOFT_TENANT=<your-azure-tenant>
AURA_MICROSOFT_SUBSCRIPTION=<your-azure-subscription>

# MongoDB connection
AURA_MONGODB_BOT_DATABASE=aura-minibot
AURA_MONGODB_URI=mongodb://mongodb:27017?authSource=admin
AURA_MONGODB_USERNAME=admin
AURA_MONGODB_PASSWORD=pass
MONGO_INITDB_ROOT_USERNAME=admin
MONGO_INITDB_ROOT_PASSWORD=pass

# Npm Auth Token
NPM_TOKEN=<your-npm-auth-token>
# NPM_AUTH=<your-optional-local-npm-auth-config>
# NPM_AUTH_SCOPE=<your-optional-local-npm-packages-scope>

# LOCALES
AURA_DEFAULT_LOCALE=<your-locale>
AURA_DEFAULT_TIME_ZONE=<your-time-zone>

AURA_PHONE_COUNTRY_CODE=ES
AURA_SERVICE_ENVIRONMENT=DEV

AURA_HOST_SERVICE_URL=http://aura-minigroot:8080
AURA_KPI_STORE_MODE=file

Example of ngrok.yml file

version: 3
agent:
  authtoken: <your-auth-token>
  web_addr: 0.0.0.0:4040
tunnels:
  minigroot:
    proto: http
    addr: aura-minigroot:8080

Example of config-groot.env file

AURA_MICROSOFT_APP_ID=<your-groot-app-id>
AURA_MICROSOFT_APP_PASSWORD=<your-groot-app-password>

Example of config-bot.env file

AURA_MICROSOFT_APP_ID=<your-bot-app-id>
AURA_MICROSOFT_APP_PASSWORD=<your-bot-app-password>

NOTE: Set all <param> from ngrok.yml, config.env, config-groot.env, config-bot.env and docker-compose.yml to your needs.

The docker-compose.yml file starts MongoDB, azurecli, ngrok, minigroot and minibot containers and exposes minigroot, minibot, MongoDB and ngrok ports (8080, 8081, 27017 and 4040 respectively).

The environments can be started with the command:

docker-compose up -d

Work with Aura minibot and install new dialogs

To work with new dialogs on minibot, follow the steps below:

Place a copy of docker-compose.yml, config-bot.env, config-groot.env, config.env and ngrok.yml in the working directory and create a packages directory to contain the dialogs source code.
Start the environment from shell with the command:
```
docker-compose up -d
```
If VSCode is used, you can connect/attach to the aura-minibot container, so you can work as local minibot version.
Minibot with the new dialog is located at /opt/aura-bot/aura-mini-bot. The current dialog sources (TypeScript files) are located at /tmp/dialogs, so you can work as non-container version.
Azure endpoint must be updated. This can be made by simply right clicking on the azcli container. Then, click on Show Container Log.

This will show in the integrated terminal a message with the URL that must be opened in a web browser and the code needed to authenticate in Azure.

When the URL is opened, an insert code request will appear on web navigator.
If no active session exists, Azure credentials must be inserted.
After credentials are set, a successful message will appear and bot endpoint will be updated.

Install Dialogs

At this stage, you can install a new dialog or an existing one, as well as update or remove dialogs.

Install a new dialog

To install new dialogs on minibot, another run task is included. To use it, click on Run button (#1 on next image), select Install dialogs from dropdown (#2 on next image) and click on on start debugging (#3 on next image).

This action will build and pack the dialogs from its source code and insert them into the minibot, but this action will not start minibot.

Install an existing dialog

Installing one or more than one existing dialog can be useful for developers, as they can use them as a reference. To install an existing dialog on the minibot container, we firstly need to add it to the minibot source code, inside the packages/ folder.

In the following example, we have added three dialog libraries: bill-col, common and factotum-test.

To add the dialogs to the minibot container, follow these steps:

Click on “File” -> “Add Folder to Workspace”
In the “Add Folder to Workspace” input text bar, type in “/tmp/dialogs/”. A list of dialog libraries passed by volume to the container will be shown. Click “Ok” to add them to the minibot container.
At this point, we will be able to see the list of dialogs passed by volume in our VS Code File Explorer.
We can now proceed to install new dialogs, if required, as shown above.

Run Aura minibot

To get minibot running click on Run (#1 on next image) and then click on start debugging (#2 on next image). This action will not install new dialogs from its source (/tmp/dialogs).

This action will start minibot so it can be debugged as normally.

Update a single dialog

⚠️ Before you can update a single dialog, you must perform the task Install dialogs.

To update a dialog independently click on Update Dialog. The task will ask for the name of the dialog folder inside /tmp/dialogs.

Remove a Dialog

To delete a dialog, temporarily you can delete it from the file /opt/aura-bot/aura-mini-bot/sources/plugin-config.json

To permanently remove it you have to delete its folder inside /tmp/dialogs. Then run the Install Dialog or Update Dialog task.

Working with Mocks in Aura minibot

It is possible to use Mocks to simulate external HTTP services. This is done using a tool called Nock.

In order to use custom Mocks we must:

Configure the environment variables that we are going to modify, which are usually the endpoints to the services to impersonate.
Configure the data for Nock.
If necessary, create a custom response file in JSON format.

To work with custom Mocks it is necessary to create this file and directory structure:

Once the container is generated, this folder will be linked to:

mock-configuration/environment.env

It contains the necessary environment variables. These environment variables will replace the ones configured in the libraries (dialogs).

mock-configuration/mocks/nock-items.json

This file contains the configurations for the Nock tool.

The general format is as follows:

       "name": "<NAME>",
       "var": "<ENVIRONMENT VARIABLE WITH ENDPOINT_>,
       "method": "<HTTP METHOD>",
       "regex": "<REGEX TO ACTIVATE>", (Optional. Mandatory if does not exist path),
       "path": <PATH TO ACTIVATE>, (Optional. Mandatory if does not exist regex)
       "reply": {
           "status": <HTTP STATUS>,
           "response": <HTTP RESPONSE> (Optional.  Mandatory if does not exist file),
           "file": <FILENAME> (Optional.  Mandatory if does not exist response),
       }

A general application example is shown below:

Example

[
    {
        "name": "Channels configuration",
        "var": "AURA_CHANNELS_CONFIGURATION_API_ENDPOINT",
        "method": "get",
        "regex":"\/channels",
        "reply": {
            "status": 200,
            "file": "channels-configuration-mock.json"
        }
    },
    {
        "name": "Skills configuration",
        "var": "AURA_CHANNELS_CONFIGURATION_API_ENDPOINT",
        "method": "get",
        "regex": "\/skills",
        "reply": {
            "status": 200,
            "file": "skills-configuration-mock.json"
        }
    },
    {
        "name": "Authorization",
        "var": "AURA_AUTHORIZATION_ENDPOINT",
        "method": "get",
        "regex":"^/.*",
        "reply": {
            "status": 200,
            "file": "authentication-mock.json"
        }
    },
    {
        "name": "FP Terms and conditions API GET",
        "var": "AURA_TERMS_AND_CONDITIONS_ENDPOINT",
        "method": "get",
        "regex": "\/v0",
        "reply": {
            "status": 404,
            "response": {}
        }
    },
    {
        "name": "FP Terms and conditions API POST",
        "var": "AURA_TERMS_AND_CONDITIONS_ENDPOINT",
        "method": "post",
        "regex": "\/v0",
        "reply": {
            "status": 200,
            "response": { "status": "accepted" }
        }
    }
]

mock-configuration/mocks/mock-files

If the configuration of one of the Nock entries requires a file for the response it must be contained in this directory.

Enable Custom Mocks

To enable custom Mocks, run the task “Enable Custom Mocks”.

Disable Custom Mocks

To deactivate the custom Mocks and leave everything with the configuration you have the default dialogs you have to run the task “Disable Custom Mocks”.

Aura minibot start-up messages

The start-up messages of the minibot are the following ones:

Minibot start-up messages

/opt/aura-bot/aura-mini-bot/sources #  /usr/bin/env AURA_LOGGING_LEVEL=DEBUG AURA_LOGGING_FORMAT=dev 'NODE_OPTIONS= --require /root/.vscode-server/bin/dc96b837cf6bb4a
f9cd736aa3af08cf8279f7685/extensions/ms-vscode.js-debug/src/bootloader.js  --inspect-publish-uid=http' 'VSCODE_INSPECTOR_OPTIONS=:::{"inspectorIpc":"/tmp/node-cdp.285
-8c9b4a1b-1.sock","deferredMode":false,"waitForDebugger":"","execPath":"/usr/local/bin/node","onlyEntrypoint":false,"autoAttachMode":"always","mandatePortTracking":tr
ue,"fileCallback":"/tmp/node-debug-callback-0cff3d0edb5d6058"}' /usr/local/bin/node ./lib/index.js 
Debugger attached.
DEBUG No existing CONFIG_FILE (undefined) found, using only process.env {
        module: 'ConfigurationManager',
        corr: 'aura-system',
        version: 'not-reachable',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Environment configuration loaded {
        module: 'ConfigurationManager',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Starting HttpMonkeyPatcher {
        module: 'StartService',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG HttpMonkeyPatcher starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  HttpMonkeyPatcher started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG MiniBotServiceMock starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  MiniBotServiceMock started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG AuraCurrentChannelsConfiguration starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  AuraCurrentChannelsConfiguration started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG AuraChannelsConfiguration starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  AuraChannelsConfiguration started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Connector starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Setting connection with options {
        module: 'connector',
        configuration: { maxPoolSize: 60, ssl: false },
        corr: 'no-correlator',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Connector started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG KpiHandler starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG KPIFileWriter started {
        module: 'kpi-entity-writer',
        corr: '',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  KpiHandler started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG PluginManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  All plugins were loaded successfully {
        module: 'LoadManager',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  PluginManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG LocaleManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  LocaleManager initialized {
        module: 'locale-manager',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  LocaleManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG AuraCacheManagement starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Module AuraCacheManagement has been started. {
        module: 'aura-cache-management',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  AuraCacheManagement started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG ChannelDataValidator starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Successfully loaded validator schema /opt/aura-bot/aura-mini-bot/node_modules/@telefonica/aura-models/resources/channel-data/3.1.0/request/channeldata-3.1.0-request.schema.json {
        module: 'channel-data-validator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Successfully loaded validator schema /opt/aura-bot/aura-mini-bot/node_modules/@telefonica/aura-models/resources/channel-data/3.1.0/response/channeldata-3.1.0-response.schema.json {
        module: 'channel-data-validator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  ChannelDataValidator started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG AuraSessionManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Index created: [object Object] {
        module: 'connector',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Index created: [object Object] {
        module: 'connector',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  AuraSessionManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG FileManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  FileManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG PrometheusRegex starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  PrometheusRegex started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG UserProfileManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  UserProfileManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG AuraBotServer starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Middleware: BatchOutgoingMessageMiddleware loaded. {
        module: 'aura-bot-server',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG speak processor rules wont be applied, AURA_MIDDLEWARE_SPEAK_PROCESSOR {
        module: 'SpeakMiddleware',
        corr: 'no-correlator',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Middleware: SpeakMiddleware loaded. {
        module: 'aura-bot-server',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  'suggestionDbCache' has been created with options: [object Object] {
        module: 'aura-cache-management',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG adding trigger conditions {
        module: 'RoutingMap',
        trigger: [ { intent: 'intent.internal.context-filters-send-resource' } ],
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Route intent.internal.context-filters-send-resource related to context-filter:send-resource {
        module: 'RoutingMap',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG adding trigger conditions {
        module: 'RoutingMap',
        trigger: [ { intent: 'intent.internal.context-filters-send-resource.v3' } ],
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Route intent.internal.context-filters-send-resource.v3 related to context-filter:send-resource-v3 {
        module: 'RoutingMap',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG adding trigger conditions {
        module: 'RoutingMap',
        trigger: [ { intent: 'intent.internal.unexpected.file' } ],
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
DEBUG Route intent.internal.unexpected.file related to unexpected-file-core {
        module: 'RoutingMap',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  AuraBotServer started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }
INFO  Server listening to 8081 {
        module: 'aura-bot-server',
        corr: 'aura-system',
        version: '8.30.0',
        app: 'aura-bot',
        host: 'c77f96ee7285'
      }

Once this step is done, developers will have their local Aura instance up and running.

Aura minigroot start-up messages

The start-up messages of the minigroot are the following ones:

Minigroot start-up messages

DEBUG Environment configuration loaded {
        module: 'configuration-manager',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG Starting HttpMonkeyPatcher {
        module: 'start-service',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG AuthenticationApiKey starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  AuthenticationApiKey started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG MiniBotServiceMock starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  MiniBotServiceMock started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG Connector starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG Setting connection with options {
        module: 'connector',
        configuration: { maxPoolSize: 60, ssl: false },
        corr: 'no-correlator',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Connector started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG LocaleManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  LocaleManager initialized {
        module: 'locale-manager',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  LocaleManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG AuraCurrentChannelsConfiguration starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  AuraCurrentChannelsConfiguration started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG AuraSkillConfiguration starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  1 skill have been loaded {
        module: 'aura-skill-configuration',
        skillsNames: [ 'aura-bot' ],
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  AuraSkillConfiguration started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG ChannelDataValidator starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Successfully loaded validator schema /opt/aura-groot/aura-mini-groot/node_modules/@telefonica/aura-models/resources/channel-data/3.1.0/request/channeldata-3.1.0-request.schema.json {
        module: 'channel-data-validator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Successfully loaded validator schema /opt/aura-groot/aura-mini-groot/node_modules/@telefonica/aura-models/resources/channel-data/3.1.0/response/channeldata-3.1.0-response.schema.json {
        module: 'channel-data-validator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  ChannelDataValidator started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG KpiHandler starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG KPIFileWriter started {
        module: 'kpi-entity-writer',
        corr: '',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  KpiHandler started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG PrometheusManager starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  PrometheusManager started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG AuraGrootCache starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
WARN  AuraGrootCache could not be started, no instance returned at init. {
        module: 'orchestrator',
        error: 'AuraGrootCache could not be started, no instance returned at init.',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG Server starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Skills have been updated {
        module: 'activity-handler',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG SkillsChannelMap {
        module: 'activity-handler',
        skillsChannelMap: {
          'novum-mytelco': '366de758-14aa-4527-a897-d04f165d80da',
          whatsapp: '366de758-14aa-4527-a897-d04f165d80da',
          'aura-channel-factory-web': '366de758-14aa-4527-a897-d04f165d80da',
          'aura-channel-factory-mobile': '366de758-14aa-4527-a897-d04f165d80da',
          'novum-mytelco-qa': '366de758-14aa-4527-a897-d04f165d80da',
          'movistar-plus': '366de758-14aa-4527-a897-d04f165d80da',
          'set-top-box': '366de758-14aa-4527-a897-d04f165d80da',
          'set-top-box-haac': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-ner': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-gazetteer': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-ner-gazetteer': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-domain-selector': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-disam': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-no-disam': '366de758-14aa-4527-a897-d04f165d80da',
          whatsapp2: '366de758-14aa-4527-a897-d04f165d80da',
          'qa-disam-sugg': '366de758-14aa-4527-a897-d04f165d80da',
          'qa-disam-sugg-black': '366de758-14aa-4527-a897-d04f165d80da',
          'global-video-platform': '366de758-14aa-4527-a897-d04f165d80da',
          'whatsapp-1004': '366de758-14aa-4527-a897-d04f165d80da',
          emulator: '366de758-14aa-4527-a897-d04f165d80da'
        },
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Module: Server, loaded. {
        module: 'aura-groot-server',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Server started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
DEBUG HttpMonkeyPatcher starting {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  HttpMonkeyPatcher started. {
        module: 'orchestrator',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  I Am Groot!!! {
        module: 'start-service',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }
INFO  Module: Server, listening to 8080 {
        module: 'aura-groot-server',
        corr: 'aura-system',
        version: '1.23.0',
        app: 'aura-groot',
        host: '12c481794fce'
      }

Test the bot

Now, the bot is ready to receive messages through Microsoft’s Direct Line 3.0 protocol.

POSTMAN can be used as a client to send messages to the bot and check the replies from the bot. To be able to do this task, please use a Microsoft POSTMAN collection for Direct Line.

Create a Direct Line token

Create a Direct Line token to be able to talk with your bot. This can be done in the Azure portal: Firstly, go to the bot service resource, and then to Direct Line channel configuration.

If you click on Direct Line, a new side window will open on the right hand side of the screen where you can see your bot keys. At this stage, click on the eye icon to view they key and copy it, so it can be used later from POSTMAN.

Publish your bot

The Aura instance is running locally in your machine.

Now, you should publish it, so it is available to the world. It can be deployed in Azure or similar clouds, but we recommend to use some applications that allow you to generate an external URL, such as ngrok or Localtunnel. You have to expose the 8080 port of your machine, which is the default port used by Aura.

_> ngrok http 8080
_> lt --port 8080

An URL like this is obtained: https://adf65ab5.ngrok.io https://localtunnel.github.io/www/

This is the URL you have to set in the Configuration section of your bot in Azure portal.

NOTE: This process is already done automatically if you use the all-in-one solution with docker-compose.

Test from POSTMAN

Once the POSTMAN collections provided by Microsoft are downloaded, store them in the same folder and import the folder from POSTMAN (File -> Import -> Import Folder).
Set the DirectLine secret in the POSTMAN environment. Select the right environment file and then click on the Gears icon, both are located on top right.

Select the Direct Line 3.0 POSTMAN environment:
Enter the secret key value copied in previous steps inside the INITIAL VALUE and CURRENT VALUE of directLineSecret variable, so other requests can use it. This secret key is the responsible to tell Microsoft which bot has to reach once we send requests to DirectLine 3.0 endpoints.

Once this information is filled, execute the requests step by step, as shown below:

Start conversation response:

{
  "conversationId": "BZ3zYAXMr1VFzElZ369fbm-a",
  "token": "<token>.ew0KICAiYm90IjogImF1cmEtYm90LWxvY2FsLWFkdmwiLA0KICAic2l0ZSI6ICIwSEwtQjdCLUhqOCIsDQogICJjb252IjogIkJaM3pZQVhNcjFWRnpFbFozNjlmYm0tYSIsDQogICJuYmYiOiAxNTczNjUwMDkwLA0KICAiZXhwIjogMTU3MzY1MzY5MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.GvmD7MI7fBw1mjtSD_bzD2xW9X3G7l-Pd64HvchADls1SuOmYvisR-PKcxGCoVkHN3g2KRsgFw6oyMf93jPT7E0ejM52j-etegl1nOLF2XUkM3TzM9vVig9qDhfAdQFxaxSeAV3zOKdCGbofH4PklscGKrmtEpnD2LpWmc-vHoMlx6gpBQaQaCtwykpEWceJ4cmd8ffkF3aCM1mnMyf-x2TZrH15URmPMPBdZ37y4-8pN_EGmNqLujOtuZgXbZG7s1tksk4LUhMuntRHLq6mwQrTvurd4fUdWOz7rO547RT9DymAQCfcuI0S_7buZN8Ii-4Dcwx0ByiGj932zhQXhA",
  "expires_in": 3600,
  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/BZ3zYAXMr1VFzElZ369fbm-a/stream?watermark=-&t=<token>.ew0KICAiYm90IjogImF1cmEtYm90LWxvY2FsLWFkdmwiLA0KICAic2l0ZSI6ICIwSEwtQjdCLUhqOCIsDQogICJjb252IjogIkJaM3pZQVhNcjFWRnpFbFozNjlmYm0tYSIsDQogICJuYmYiOiAxNTczNjUwMDkwLA0KICAiZXhwIjogMTU3MzY1MDE1MCwNCiAgImlzcyI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iLA0KICAiYXVkIjogImh0dHBzOi8vZGlyZWN0bGluZS5ib3RmcmFtZXdvcmsuY29tLyINCn0.Hcl15E483KyRlD5geEZSX2zWP5ihpnwQAl09Ah3aKLvL5Hl2kkiirllZppSZmxl8KZKb84BOav8MYlQCkrLtbQ5c5BA0s0DYH469-jNAryhQYIwDVwNdep_0OwZvRSnsgxJU4FOqx-0rpvY26W86HrXM4vhSrVYewcRLvm_F3e5dDGekfIDX3krvsqT4tykmI-RTaR20jeErDucoJvW5gLKfk1uduVnCllcNG6Vwn4zsm6hhPy7Q0Xcq9OfQlD17Bc8J3XPmJiv7vzG48ooNA7wr_E1ju2uElgRh5Iore7wjT3H4gQNVXmRDSNKmhACQv6KfU5CJLmtyELjfsRvyAQ",
  "referenceGrammarId": "55db166a-b049-c059-b26c-07296f680752"
}

The conversationId field is extracted automatically from this first request and is included in the rest of the requests.

Send message sends an AuraCommand in order to avoid the NLP process, so the dialog is triggered without NLP. You should edit the body request to be similar to the following one (remember to change the intent name to the one set in your library):
```
  {
    "type": "message",
    "from": {
        "id": "b1a72a34-626e-4c54-b2f7-6b45acf743a2"
    },
    "locale": "es-ES",
    "textFormat": "plain",
    "timestamp": "2019-11-06T17:33:31.319Z",
    "channelData": {
      "auraCommand": {
          "type": "suggestion",
          "value": {
              "intent": "intent.greetings-demo.greetings"
          }
      }
    }
}
```
Where:
- from.id is the user who is going to access the bot. This information can be obtained from the file /sources/files/mock-files/authentication-mock.json, choosing an userAuraId.
- auraCommand.value.intent contains the intent (dialog) to be reached. This information can be obtained in the files located in dev/settings/dialog-config.xx-xx.json (where xx-xx is the locale referred to the country, i.e., es-gb) in the library repository or local development in case of a new one.
```
{
  "dialogs": [
    {
      "triggerConditions": [
        {
          "intent": "intent.greetings-demo.greetings"
        }
      ],
      "id": "greetings",
      "onlyIn": ["movistar-plus", "set-top-box"]
    }
  ],
  "name": "greetings-demo"
}
```
If everything worked fine, once the request is sent, it is shown in the ngrok console. Also, the dialog activation is shown on the bot console.

ngrok:

ngrok example

  HTTP Requests
  -------------

  POST /api/messages             202 Accepted
  	Bot (consola Visual Studio Code):
  INFO  HTTP API request GET authorization-mock/ca9961f9-c6f0-3acd-5c72-ce2719f43ec9 {
      domain: 'authorization-mock',
      method: 'GET',
      path: '/ca9961f9-c6f0-3acd-5c72-ce2719f43ec9',
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG HTTP API response GET authorization-mock/ca9961f9-c6f0-3acd-5c72-ce2719f43ec9 200 {
      domain: 'authorization-mock',
      method: 'GET',
      status: 200,
      path: '/ca9961f9-c6f0-3acd-5c72-ce2719f43ec9',
      drt: 4,
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  HTTP API response GET authorization-mock/ca9961f9-c6f0-3acd-5c72-ce2719f43ec9 200 {
      domain: 'authorization-mock',
      method: 'GET',
      status: 200,
      path: '/ca9961f9-c6f0-3acd-5c72-ce2719f43ec9',
      drt: 4,
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Starting recognizer AuraCommandRecognizer {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'recognizer-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Intent set {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      intent: {
        intents: { 'intent.common.greetings': [Object] },
        entities: [],
        text: '',
        answers: undefined,
        promptCheck: true,
        utm: { source: 'channel_name', medium: 'text' }
      },
      module: 'aura-context-utils',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  AuraCommandRecognizer:6e204898-9fee-4006-a17e-7e6851fb8fca {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      intent: '{"intent.common.greetings":{"score":1}}',
      module: 'recognizer-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG End recognizer AuraCommandRecognizer. Result: {"intents":{"intent.common.greetings":{"score":1}},"entities":[],"text":"","promptCheck":true,"utm":{"source":"channel_name","medium":"text"}} {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'recognizer-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Finalize recognizers. Result: {"intents":{"intent.common.greetings":{"score":1}},"entities":[],"text":"","promptCheck":true,"utm":{"source":"channel_name","medium":"text"}} {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'incoming-message-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Break prompt {
      topIntent: {
        intent: 'intent.common.greetings',
        score: 1,
        entities: [],
        type: 'suggestion'
      },
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'incoming-message-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Clear stack evaluation: Prompt Options: No Prompt detected. Score 1, min-score threshold: 0.95 {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'aura-context-utils',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Request received {
      domain: '26eba81ecfb9.ngrok.io',
      method: 'POST',
      path: '/api/messages',
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'AuraBotServer',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Running dialog with Message Activity. {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'aura-bot',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  Recognize this intent pre-contextfilter {
      intent: '{"intent":"intent.common.greetings","score":1,"entities":[],"type":"suggestion"}',
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'main',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG routing resolution {
      recognizer: 'intent.common.greetings',
      result: undefined,
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'RoutingMap',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  There is no dialog to handle this message {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'main',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  Outgoing activity {
      text: 'Vaya, parece que no soy capaz de entenderte. Inténtalo de nuevo',
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'outgoing-message-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Finalize middlewares pipeline {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'outgoing-message-middleware',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG Dialog undefined finished, NO suggestions. {
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'main',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  Response returned 200 POST /api/messages {
      method: 'POST',
      status: 200,
      path: '/api/messages',
      drt: 35,
      corr: '11efcaff-67fb-46cd-be7f-6a54f68fd926',
      module: 'AuraBotServer',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  HTTP API request POST login.microsoftonline.com/botframework.com/oauth2/v2.0/token {
      domain: 'login.microsoftonline.com',
      method: 'POST',
      path: '/botframework.com/oauth2/v2.0/token',
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG HTTP API response POST login.microsoftonline.com/botframework.com/oauth2/v2.0/token 200 {
      domain: 'login.microsoftonline.com',
      method: 'POST',
      status: 200,
      path: '/botframework.com/oauth2/v2.0/token',
      drt: 1974,
      body: '{"token_type":"Bearer","expires_in":86398,"ext_expires_in":86398,"access_token":"<token>"}',
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  HTTP API response POST login.microsoftonline.com/botframework.com/oauth2/v2.0/token 200 {
      domain: 'login.microsoftonline.com',
      method: 'POST',
      status: 200,
      path: '/botframework.com/oauth2/v2.0/token',
      drt: 1974,
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  HTTP API request POST directline.botframework.com/v3/conversations/IiKY7bzb1Pd5VdtN4FZKmB-a/activities/IiKY7bzb1Pd5VdtN4FZKmB-a%7C0000000 {
      domain: 'directline.botframework.com',
      method: 'POST',
      path: '/v3/conversations/IiKY7bzb1Pd5VdtN4FZKmB-a/activities/IiKY7bzb1Pd5VdtN4FZKmB-a%7C0000000',
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  DEBUG HTTP API response POST directline.botframework.com/v3/conversations/IiKY7bzb1Pd5VdtN4FZKmB-a/activities/IiKY7bzb1Pd5VdtN4FZKmB-a%7C0000000 200 {
      domain: 'directline.botframework.com',
      method: 'POST',
      status: 200,
      path: '/v3/conversations/IiKY7bzb1Pd5VdtN4FZKmB-a/activities/IiKY7bzb1Pd5VdtN4FZKmB-a%7C0000000',
      drt: 185,
      body: '{\r\n  "id": "IiKY7bzb1Pd5VdtN4FZKmB-a|0000001"\r\n}',
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  INFO  HTTP API response POST directline.botframework.com/v3/conversations/IiKY7bzb1Pd5VdtN4FZKmB-a/activities/IiKY7bzb1Pd5VdtN4FZKmB-a%7C0000000 200 {
      domain: 'directline.botframework.com',
      method: 'POST',
      status: 200,
      path: '/v3/conversations/IiKY7bzb1Pd5VdtN4FZKmB-a/activities/IiKY7bzb1Pd5VdtN4FZKmB-a%7C0000000',
      drt: 185,
      corr: 'no-correlator',
      module: 'HttpMonkeyPatcher',
      version: '6.0.0',
      app: 'aura-bot',
      host: 'cc45bbf4b438'
    }
  ```
</details>

Inside POSTMAN, use “Receive activities” request to follow up all the messages sent to and from the bot.

Example

{
"activities": [
  {
    "type": "message",
    "id": "IiKY7bzb1Pd5VdtN4FZKmB-a|0000000",
    "timestamp": "2021-01-28T16:02:49.6587305Z",
    "serviceUrl": "https://directline.botframework.com/",
    "channelId": "directline",
    "from": {
      "id": "ca9961f9-c6f0-3acd-5c72-ce2719f43ec9"
    },
    "conversation": {
      "id": "IiKY7bzb1Pd5VdtN4FZKmB-a"
    },
    "textFormat": "plain",
    "locale": "es-ES",
    "channelData": {
      "auraCommand": {
        "type": "suggestion",
        "value": {
          "intent": "intent.common.greetings"
        }
      }
    }
  },
  {
    "type": "message",
    "id": "IiKY7bzb1Pd5VdtN4FZKmB-a|0000001",
    "timestamp": "2021-01-28T16:02:52.6086472Z",
    "channelId": "directline",
    "from": {
      "id": "bot-antonio",
      "name": "bot-antonio"
    },
    "conversation": {
      "id": "IiKY7bzb1Pd5VdtN4FZKmB-a"
    },
    "text": "Vaya, parece que no soy capaz de entenderte. Inténtalo de nuevo",
    "inputHint": "acceptingInput",
    "channelData": {
      "correlator": "11efcaff-67fb-46cd-be7f-6a54f68fd926"
    },
    "replyToId": "IiKY7bzb1Pd5VdtN4FZKmB-a|0000000"
  }
],
"watermark": "1"
}

Develop a new use case

Once the use case is developed following the guidelines included in the document Use cases development over Aura Bot, it is required to follow the step below:

Run the command npm pack from the library root folder to generate a .tgz with the library packed. Now, the library is ready to be imported and used by the minibot.

Minibot set-up to import and run the library

Copy the path where the .tgz file is located (right click and copy path in VSCode):
Go to root/ folder in your minibot project and run:
```
  npm install <path copied>`
```
Open the plugin-config.json file and set the name of the library inside the array as below (in the sample, the library’s name is test-app):

Add the dialogs in their libraries inside aura-mini-bot/sources/files/mock-files/channels-configuration-mock.json as well:

Example of channels-configuration-mock.json

    {
      "name": "novum-mytelco",
      "prefix": "nov",
      "channel_id": "xxxxxxx",
      "fpa_auth_scopes": "device-catalog:devices-read device-stock:stock-read",
      "fpa_auth_purposes": "customer-self-service detect-abnormal-usage device-recommendations-v3 sim-upgrade-suggestion aura-read-insight-events identify-customer bolt-on-suggestion",
      "batchMessages": true,
      "notifications_enabled": true,
      "notifications_insights_mitigation": true,
      "notification_configuration": {
        "notifications_event_types_enabled": [
          {
            "id": "unusual-data-usage",
            "enabled": true,
            "push_text": "notifications:notifications.unusual-data-usage.pushText",
            "action": "usage.anomaly",
            "subscription_filters": [
              "user_id",
              "phone_number"
            ]
          }
        ],
        "notification_callback": "https://ha42ojf7mb.execute-api.us-east-1.amazonaws.com/prod/callback/xxxxx"
      },
      "dialogLibraries": [
        {
          "name": "my-library",
          "dialogs": [
            {
              "id": "my-dialog",
              "triggerConditions": [
                {
                  "intent": "intent.my-intent"
                }
              ]
            }
          ]
  ]

NOTE: We can do a copy of the content inside of the file dialog-config.json located in our original library development.

Go to dev folder and run npm run makeup-local and wait until it finishes (it will notify us through the console):
Now the library is ready to be used from the minibot. Run the minibot through VSCode debugger (using your launch.json file).

Debugging with Aura minibot

Right now, the best way to debug a dialog is from .js files located into node_modules once our packed library is installed. This is the way to avoid NPM Link dependency issues.

Breakpoints can be set in those dialog files. Once our breakpoint is reached, when we send the request from POSTMAN, the minibot will stop and it will show the debug options in VSCode:

Global use cases debugging example (personalized data)

In the following example it is shown how to debug an existing dialog with personalized data using the intent intent.billing.check. The steps to debug it from scratch are the following:

Set the channel configuration and enable the dialog in that channel.

Go to channels-configuration-mock.json located into the folder: aura-mini-bot/sources/files/mock-files
Once there, check that the dialog is enabled inside the dialogLibraries property of the desired channel:

We use the intent.billing.check name to activate the dialog through POSTMAN in future steps. Let’s see now a screenshot of the full channel configuration for this example:

From the code above, the id property must be copied to a safe place, because it will be used in the next step.

Go to aura-mini-bot/sources/files/mock-files/authentication-mock.json file located into aura-mini-bot/sources/files/mock-files/ folder.

Paste the previous value copied (id) into the id property and check that the name and prefix property fit with the channel information.

The id property is the responsible to link the user to that channel (remember that a user has to be registered on a channel).

Now we have all we need. Pay attention to auraId property, as it will be used on POSTMAN to send messages to Aura.
Go to the root node_modules folder and open the bill-check-dialog.js file in order to set the desired breakpoints:

Go to debug module in VSCode and run the minibot in debug mode.
Go to POSTMAN and send the request to start conversation. In addition, send a request with an aura command to reach bill-check dialog:
We should be able to see our minibot stops in our breakpoints set in previous steps:

As we can see in the console, we have reached the intent.billing.check as a Final recognizer result. It can be noticed that the auraData object includes the information from the authentication-mock.json file mentioned before.

Run Aura minibot against a remote environment

In cases where it is necessary or desired to test use cases against a remote test environment, the following steps should be performed.

Get the environment variables

Using the kubeconfig file that your manager or DevOps Team should provide you with, run the following commands from a Unix terminal which will generate an .env file:

  $ export KUBECONFIG=<path-to-file>
  $ (kubectl -n aura-<environment> get cm aura-bot -o json | jq -r ".data|to_entries|map(\"\(.key)=\(.value|tostring)\")|.[]" ; kubectl -n aura-<environment> get secret aura-bot -o json | jq -r ".data|to_entries|map(\"\(.key)=\(.value|tostring|@base64d)\")|.[]" ) > aura-<environment>.env

NOTE: Set all 3 of <environment> params to your needs.

NOTE: In case the command does not find jq, you must install the library by executing the following:

  $ apt-get update
  $ apt-get install jq

Modify environment file

In order for the minibot to work correctly against a remote environment, the following variables must be added at the beginning of the .env file:

  # REMOTE ENV
  AURA_ACTIVATE_MINI_BOT=false
  AURA_LOGGING_LEVEL=DEBUG
  AURA_LOGGING_FORMAT=dev

Then, we will proceed to modify the following variables:

  AURA_CHANNELS_CONFIGURATION_API_ENDPOINT=http://wiremock:8080
  AURA_COGNITIVE_ENDPOINT=http://host.docker.internal:7000/auracognitive/v3
  AURA_MONGODB_URI=mongodb://host.docker.internal:27017

And comment or delete the subsequent ones:

  # AURA_LOGGING_LEVEL=INFO
  # AURA_MICROSOFT_APP_ID=********
  # AURA_MICROSOFT_APP_PASSWORD=********

Create new docker-compose

For convenience, we will create a new docker-compose file to be able to use the minibot locally and remotely without making modifications each time. This file will be added along with the previous docker-compose.yml file.

docker-compose-remote.yml

version: '3'

services:  
  wiremock:
    image: wiremock/wiremock:2.33.2
    volumes:
      - ./mock-configuration/mocks/mock-files:/home/wiremock/__files:ro
      - ./mappings:/home/wiremock/mappings:ro
    restart: unless-stopped
    expose:
      - "8080"
    ports:
      - "4041:8080"

  mongodb:
    image: mongo:4.2
    restart: unless-stopped
    env_file:
      - config.env
    ports:
      - "27017:27017"

  aura-minigroot:
    image: auraregistry.azurecr.io/aura/aura-mini-groot:<version>
    volumes:
      - ./mock-configuration/mocks/mock-files:/opt/aura-groot/aura-mini-groot/sources/files/mock-files/
    env_file:
      - config.env
      - remote-config.env
      - config-bot.env
    restart: unless-stopped
    depends_on:
      - mongodb
    ports:
      - "8080:8080"
    entrypoint: sh -c "sh -c \"$${@}\""
    command: >
      sh -c "
        set -e
        echo $$(echo $$(nslookup host.docker.internal | grep -o 192.*) aura-bridge-outbound) >> /etc/hosts
        /opt/aura-groot/aura-mini-groot/sources/docker-entrypoint-mini-groot.sh
        sh || exit 0
      "      

  aura-minibot:
    image: auraregistry.azurecr.io/aura/aura-mini-bot:<version>
    volumes:
      - ./packages:/tmp/dialogs
      - ./mock-configuration:/opt/aura-bot/aura-mini-bot/mock-configuration
      - mock-files:/opt/aura-bot/aura-mini-bot/sources/files/mock-files
    env_file:
      - config.env
      - remote-config.env
      - config-bot.env
    restart: unless-stopped
    depends_on:
      - mongodb
    ports:
      - "8081:8081"

  azcli:
    image: mcr.microsoft.com/azure-cli:2.49.0
    depends_on:
      - ngrok
    env_file:
      - config.env
    command: >
      sh -c "
        az login --tenant $$AURA_MICROSOFT_TENANT &&
        az account set --subscription $$AURA_MICROSOFT_SUBSCRIPTION &&
        az bot update -n $$AURA_MICROSOFT_BOT_NAME -g $$AURA_MICROSOFT_RESOURCE_GROUP --endpoint $$(curl --silent http://ngrok:4040/api/tunnels | jq -r '.tunnels | map(.public_url) | .[]' | grep https)/api/messages
      "      
  ngrok:
    image: ngrok/ngrok
    command:
      - "start"
      - "--all"
      - "--config"
      - "/etc/ngrok.yml"
    volumes:
      - ./ngrok.yml:/etc/ngrok.yml
    ports:
      - "4040:4040"

volumes:
  mock-files:

NOTE: Set <version> to your needs.

Mappings for the Channels API

In order to get the configuration of locally installed use cases, and skills, create a mappings folder in the working directory and add these three files:

channels.json

  {
    "request": {
      "method": "GET",
      "urlPattern": "(.*)\/channels(.*)"
    },
    "response": {
      "status": 200,
      "bodyFileName": "channels-configuration-mock.json",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }

skills.json

{
  "request": {
    "method": "GET",
    "urlPattern": "(.*)\/skills(.*)"
  },
  "response": {
    "status": 200,
    "bodyFileName": "skills-configuration-remote-mock.json",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

This configuration will use the docker volume created in the docker-compose to be able to serve through the WireMock container the files located in /sources/files/mock-files/.

Start the minibot containers

You must use the following command to raise the containers with the new compose file:

  $ docker-compose -f ./docker-compose-remote.yml up -d

You should also use the following command to shut down the correct containers:

  $ docker-compose -f ./docker-compose-remote.yml down

Docker scaffolding

Below, you can find the complete folder and file structure with links to download them, so you can start using minibot in docker right away:

https://github.com/Telefonica/aura-mini-bot

Docs:

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

Introduction to Aura use cases

Learn what is a use case in Aura and which are the different types of experiences that can be developed

Introduction

Aura is offered as a platform to the business units to integrate it into their customer relationship channels and with a series of capabilities to create locally relevant experiences for the users. These experiences are called use cases.

A use case is a specific experience triggered by a direct request from the users that provides them with the most appropriate response to their requests due to Aura’s capability of understanding natural language, processing it and building personalized responses in real time.

Types of use cases in Aura

Use cases in Aura are divided into two main groups:

Generic questions use cases

Experiences based on frequently asked questions (FAQs), that is, the most common questions that customers can ask Aura in their interactions and that are most likely to remain constant over time. A great percentage of interactions with Aura is based on these questions.

✅ Examples of generic question use cases:

How can I get my IMEI number?
Use data abroad
Activate O2 wifi

Global use cases

Global use cases are already designed and developed by Aura Platform Team. You cannot modify their logic but use them as they are or get inspired for deploying your own experiences:

Video use cases are available.

📃 Learn how to manage global use cases in the Use Global Use Cases section.

Personalized use cases

Custom-made experiences that provide specific answers to each customer based on her data and context.

✅ Examples of personalized use cases:

Show me my last bill
Check my data consumption
Status of my complaint A-330
Check my balance
Which devices are connected to my wifi?

They are classified into two categories:

Use cases managed by the generic-dialog

The generic-dialog allows the creation of personalized experiences easily, only by means of a simple configuration, with no code development. It is available for use cases in TV channels that imply direct actions (Switch off the TV; rewind the movie 10 seconds; etc.)

Interested in these use cases?

📃 Understand what is the generic-dialog and the conditions for its use here.
📃 Learn the detailed guidelines for the generation of a use case through the generic-dialog here.

Local use cases

Custom-made experiences in Aura that can be built by constructors from scratch or inspired in a global use case.

All of them require:

Writing code over aura-bot
Training the system to understand the user’s request through Aura NLP

📃 For creating this custom-made use cases, follow the guidelines in Develop local experiences in Aura.

Docs:

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

Aura Bot development troubleshooting

Resolution of common problems, fixes and enhancements in Aura Bot

Developing a dialogs library aka plugin

Issues with aura-bot-common and @hapy/joi

How to detect it

As all the plugins run inside the aura-bot-platform, they must share the very same version of the libraries that are used across all the modules within the bot.

This is quite important because some of the common libraries provide a kind of singleton access to shared information, needed both during the core steps executions and during the dialogs execution. If the versions are not the same, then the instances will not be the same and the dialogs will not find the information where it is expected.

It is important to understand how the dependencies are resolved in nodejs: npm dependency resolution.

How to solve it

To avoid it, the proposal is to lay on the bot dependencies and just configured in the plugin a minimal version:

For example, if the library allows all versions starting from 1.8.3 (without a major change) and the bot provides the 1.13.7 (which is fixed in the package-lock.json of aura-bot), then both components will use the same one.

Although it is not an internal library, almost the very same issue happens with @hapy/joi. Do not change the version provided by aura-bot, or there would be unexpected issues with the schema merging and validation.

Example of package.json plugin

Each global library has specific dependencies. Developers should access to the library and check its corresponding package.json file.

Check an example for the “bill” global library

    "dependencies": {
        "@telefonica/aura-bot-common": "7.24.0",
        "@telefonica/aura-bot-library-util": "7.26.0",
        "@telefonica/aura-locale-manager": "7.22.0",
        "@telefonica/aura-logging": "3.10.0",
        "@telefonica/invoicing-client": "2.15.0",
        "@telefonica/mobile-balance-client": "2.14.0",
        "botbuilder": "~4.13.3",
        "botbuilder-dialogs": "~4.13.3",
        "joi": "^17.6.0",
        "moment": "^2.29.3"
    },

Example of aura-bot-platform package.json file

⚠️ This section has only descriptive purposes, as dependencies are established by Aura Global Team and OBs cannot modify this file.

Check an example of the package.json file

        "dependencies": {
        "azure-storage": "^2.10.7",
        "@azure/storage-blob": "^12.12.0",
        "@telefonica/authentication-api-client": "1.15.0",
        "@telefonica/aura-behavior-manager": "7.26.0",
        "@telefonica/aura-bot-common": "7.24.0",
        "@telefonica/aura-bot-events-client": "1.13.0",
        "@telefonica/aura-bot-library-util": "7.26.0",
        "@telefonica/aura-channel-data-handler": "7.22.0",
        "@telefonica/aura-cognitive-client": "3.15.0",
        "@telefonica/aura-configuration": "7.21.0",
        "@telefonica/aura-configuration-api-client": "1.10.0",
        "@telefonica/aura-developer-tools": "7.26.0",
        "@telefonica/aura-http-monkey-patcher": "7.14.0",
        "@telefonica/aura-kpis2": "7.20.0",
        "@telefonica/aura-locale-manager": "7.22.0",
        "@telefonica/aura-logging": "3.10.0",
        "@telefonica/aura-makeup-index-manager": "7.18.0",
        "@telefonica/aura-models": "3.14.0",
        "@telefonica/aura-mongo-handler": "7.12.0",
        "@telefonica/aura-movistar-libraries-utilities": "7.26.0",
        "@telefonica/aura-nlp-client": "3.11.0",
        "@telefonica/aura-orchestrator": "2.7.0",
        "@telefonica/aura-storage-file-manager": "7.18.0",
        "@telefonica/aura-validate-apikey": "1.7.0",
        "@telefonica/baikal-sdk": "^0.10.1",
        "@telefonica/event-bus": "3.8.0",
        "@telefonica/aura-file-manager-client": "1.10.0",
        "@telefonica/movistar-plus-cognitive-client": "3.13.0",
        "@telefonica/spleen": "^1.4.0",
        "@telefonica/user-profile-client": "3.13.0",
        "@telefonica/aura-bot-bill-library": "7.27.0",
        "@telefonica/aura-bot-cognitive-library": "7.27.0",
        "@telefonica/aura-bot-common-library": "7.27.0",
        "@telefonica/aura-bot-disambiguation-library": "7.27.0",
        "@telefonica/aura-bot-generic-library": "7.28.0",
        "@telefonica/aura-bot-handover-library": "7.27.0",
        "@telefonica/aura-bot-linking-library": "7.27.0",
        "@telefonica/aura-bot-miscellaneous-library": "7.27.0",
        "@telefonica/aura-bot-mocks-library": "7.27.0",
        "@telefonica/aura-bot-none-library": "7.27.0",
        "@telefonica/aura-bot-onboarding-library": "7.27.0",
        "@telefonica/aura-bot-services-library": "7.27.0",
        "@telefonica/aura-bot-tv-library": "7.27.0",
        "architect": "^0.1.13",
        "body-parser": "^1.19.0",
        "botbuilder": "~4.13.3",
        "botbuilder-core": "~4.13.3",
        "botbuilder-dialogs": "~4.13.3",
        "dotenv": "^8.0.0",
        "express": "^4.17.1",
        "express-prom-bundle": "^6.4.1",
        "folder-hash": "^3.3.0",
        "genversion": "^3.0.2",
        "helmet": "6.1.3",
        "html-to-text": "^7.0.0",
        "http-status": "^1.5.0",
        "http-status-codes": "^2.2.0",
        "joi": "^17.6.0",
        "merge-deep": "^3.0.3",
        "mkdirp": "^1.0.3",
        "moment": "^2.29.3",
        "moment-timezone": "0.5.28",
        "mongodb": "^3.5.8",
        "node-cache": "^5.1.0",
        "prom-client": "^13.1.0",
        "replace": "^1.2.2",
        "semver": "^7.3.4",
        "superagent": "^8.0.4",
        "uuid": "3.3.3",
        "xregexp": "^4.2.4"
    },

Docs:

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

General guidelines for building an Aura Bot dialog

Orderly steps for building a dialog over Aura Bot in a common scenario

Create the dialog’s file

The dialog is a .ts file that must be placed within the src/ folder of its library.
- Have you already created the library? Then, go ahead.
- If not, go to Build a new library section and create it.
Developers must create one .ts file for each dialog of the use case.
All dialogs must include these two mandatory components:

Parameter	Type	Comments
id	string	Dialog’s identifier
configuration	configuration	Global and specific dialog’s configuration is validated over aura-bot and passed to the dialog through the constructor, when instantiated.

The maximum size for an activity response may not exceed the maximum limit established by the Direct Line (MS) protocol under any circumstances. In case this happens, the answer is ignored and a generic text is returned to the user explaining that there are too many results.

📌 Best practices

When generating a new dialog, a general recommendation for developers is to copy another working dialog and use it as a template.
If the dialog’s code is too long or complex, it can be split into several files, in order to increase readability.
It is also a good practice to create utility files with code shared between dialogs in the same library.

The following sections include certain features that are useful for the generation of a dialog within Aura’s framework.

Management of dialogs are waterfall dialogs

The interaction with the user can be based on a single stage back-and-forth dialog (this is, the user asks Aura and Aura provides the appropriate answer back to the user) or, on the contrary, a multiple stage dialog. Currently, although the dialog is based on a single stage, all dialogs are built as waterfall dialogs.

For this purpose, you should use the Microsoft tool botbuilder-dialogs package, that contains functions to assist with the formatting of a message activity containing a list of choices.

Within its specific library, the dialog must implement the Microsoft Bot Framework 4 ComponentDialog class. Libraries have to import the dependency on “botbuilder-dialogs: “~4.13.3`. To avoid conflict in the versions of this library, aura-bot specifies the concrete version.

/**
 * Aura Bot dialog implementation for any class.
 */
export default class NameClassAuraBotDialog extends ComponentDialog {
    ...
}

As shown in the code below, the constructor must support the configuration, which includes both global and local variables (always validated variables) that the dialog can use. Additionally, the constructor can include auraDataAccessor as a second parameter. See details in Data saving in the same conversation.

    public static id: string = 'name-class-dialog';
    private configuration: Configuration;
 
    constructor(configuration: Configuration) {
        super(NameClassAuraBotDialog.id);
        this.configuration = configuration;
        // ID of child dialog that should be started anytime component is started.
        super.initialDialogId = NameClassAuraBotDialog.id;
        // Define the conversation flow using a waterfall model.
        super.addDialog(new WaterfallDialog(NameClassAuraBotDialog.id, [
            this.method1.bind(this),
            this.method2.bind(this)
            // ...
            this.methodN.bind(this)
        ]));
       }

If the dialog requires the use of prompts, please read Prompts treatment section for its declaration within the dialog file.

Retrieving data from clients

If the dialog’s conversational flow requires to fetch user’s data, the dialog code must include the specific instructions to call an API (Kernel API or external API). Therefore, at library’s level, it is required to import the client of the corresponding API. In case of Kernel APIs, please read the section Create or update an API client.

Basic utilities for building a dialog

The current section extracts specific procedures based on Microsoft Bot Framework 4 functionalities that are of particular importance for the generation of a dialog within aura-bot.

Localized text

const correlator = ContextUtils.getCorrelator(stepContext.context);
const auraUser: AuraUserBaseModel<any> = ContextUtils.getAuraUser(stepContext.context);
const text = this.localizer.getText('common:common.greetings.main', auraUser, correlator)

Code for localizing this id: common:common.greetings.main

Dialogs can include a localizer as an attribute that points to the single instance of the class that was initialized during aura-bot start-up. this.localizer = LocaleManager.instance;

Alternatively, you can use the getLiteral method from @telefonica/aura-bot-utilities/lib/aura-bot-library-util library without having to obtain user or correlator as follows: const text = getLiteral(context)('common:common.greetings.main')

Send a simple text

The example below shows how to send a simple localized text.

await stepContext.context.sendActivity(text);
return await stepContext.endDialog();

ℹ️ In BotBuilder v4, nothing is sent (text cannot be sent) in the endDialog, only that the current dialog is finished and the result of the dialog’s finalization.

Complex messages

There is big flexibility composing user’s messages. They can be built with MessageFactory using the Bot Framework, built by your own, combined, etc.

In this section, certain flags are included that can help the channel understand the conversation flow.

InputHint

InputHint allows building messages in different modes, indicating to the destination channel when it is waiting for new messages or not.

For more information, read InputHints enum Microsoft documentation.

AcceptingInput: bot is passively ready for input, but it is not waiting a response from the user. (Example: last message in the dialog)
ExpectingInput: bot is waiting a response from the user. (Example: when a prompt is sent)
IgnoringInput: bot is not ready to receive input. (Example: when several messages are sent together excepting the last one)

Add inputHint in the activity when it is necessary to change the default behavior:
messageOneOfFour.inputHint = InputHints.IgnoringInput

Be careful with the default value given in the activities, as it is not always the desired behavior.

When constructing a complex message to the user in which, for example, partial activities are joined with attachment cards for finally sending a prompt or some parts are built with Factory and others are not, it is necessary to make sure that the final message contains the desired InputHint. In this example, the result prompt has an invalid InputHint:

// Example with INVALID InputHint:
// the message variable will have acceptingInput as default.
const message: Partial<Activity> = MessageFactory.text('My text');
const cardActions: CardAction[] = options.map(q => ({
	type: ActionTypes.ImBack,
    value: q,
    title: q
}));
// the attachment variable will have acceptingInput as default
const attachment: Partial<Activity> = MessageFactory.attachment(
   CardFactory.heroCard(null, null, cardActions)
);
const promptOptions: PromptOptions = {
 	prompt: { ...message, ...attachment },
	choices: ChoiceFactory.toChoices(cardActions)
};
// Prompt will have acceptingInput. IT IS NOT VALID!

The example with a valid InputHint is shown below:

// Example with valid InputHint:
const message: Partial<Activity> = MessageFactory.text('My text');
message.inputHint = InputHints.ExpectingInput;
const cardActions: CardAction[] = options.map(q => ({
	type: ActionTypes.ImBack,
    value: q,
    title: q
}));
const attachment: Partial<Activity> = MessageFactory.attachment(
   CardFactory.heroCard(null, null, cardActions)
);
attachment.inputHint = InputHints.ExpectingInput;
const promptOptions: PromptOptions = {
 	prompt: { ...message, ...attachment },
	choices: ChoiceFactory.toChoices(cardActions)
};
// The prompt will have expectingInput as expected in a Prompt

HasMoreMessages flag

There is another legacy flag in channelData: hasMoreMessages (created in Aura) that indicates whether aura-bot will send more messages to the channel.

Currently, all channels should use batch-outgoing-message-middleware which stacks all the messages related to an incoming activity together with the Suggestions and automatically sets hasMoreMessages field to proper value (only when messages are processed in batch mode.

Note that even though the hasMoreMessages flag is sent in some cases (if in batch mode and channel is configured to do so), it is preferable to use the standard message property inputHint, that is always available and will be maintained in the future.

It is the recommended way to configure channels and aura-bot, so messages are properly marked up both with hasMoreMessages and the proper Microsoft Bot Framework field, inputHint.

Prompts treatment

ℹ️ Before facing this section, see how the special prompts recognition works in the prompt-check-recognizer-middleware.

The following list of prompt recognizers are available in Aura:

Attachment prompt: it asks for one or more attachments, such as a document or image.
Choice prompt: it asks for a choice among a set of options.
Date-time prompt: it asks for a date-time.
Number prompt: it asks for a number.
Text prompt: it asks for a general text input.
Custom prompt: prompt that can be personalized with different options.

Break prompt and NLP Recognition

When a dialog returns a prompt and thus is waiting for an action, then the user can choose one of the prompt answers or can decide to carry out another option.

In this second case, the prompt must be broken (if conditions are fulfilled) and the aura-bot main-dialog redirects to the new dialog.

By default, prompts have NLP recognition. When the user interacts with the prompt, the prompt-recognizer is executed and tries to recognize the user’s intention. But, also by default, if the None intent is recognized, it will not break the prompt.

To make the process of prompt breaking flexible, Aura provides a default behavior and offers flags that allow the default behavior to be changed. These flags should be added during the instantiation of the prompt:

disableRecognition: enabling this flag, NLP recognition is disabled, preventing to break the prompt. (It only affects to prompts without choices). Use: prompts without choices.
enableNone: enabling this flag, if NLP recognizer has recognized the None intent, this intent is allowed to break the prompt (by default, None intent can never break a prompt). Use: all types of prompts with NLP recognition.
useValueAsCommand: using this flag, the prompt choices are interpreted as text commands, and, when properly configured, the conversation flow is redirected to the intent defined by the command. Use: only with choice prompts.

These flags should be added in the validations attribute inside promptOptions.

For example, if a prompt wants to disable NLP recognition, it should be marked as follows:

const promptOptions: PromptOptions = { 
	prompt: description, 
	validations: { disableRecognition: true } 
}; 
return await stepContext.prompt('ID_PROMPT', promptOptions);

Disable ordinals and numbers recognition in prompt choices

To avoid the recognition of ordinals and numbers in prompts, two steps should be followed:

First, add the proper flags in promptOptions:

const promptOptions: PromptOptions = { 
  ...
  validations: { 
        findChoicesOptions: {
            recognizeNumbers: false,
            recognizeOrdinals: false
        }
    } 
};

After that, a new validation method should be added to the prompt:

getRetriesValidatorAndOverwriteRecognizerResult 
const connectPrompt = new ChoicePrompt('promptName', PromptUtils.getRetriesValidatorAndOverwriteRecognizerResult(0));

Retries handling in prompt choices

This section includes the procedure for managing prompt attempts. In the botbuilder-js code, the function continueDialog must include the following code in the Prompt class:

const recognized: PromptRecognizerResult<T> = await this.onRecognize(dc.context, state.state, state.options);
// Validate the return value
let isValid = false;
if (this.validator) {
    if (state.state['attemptCount'] === undefined) {
        state.state['attemptCount'] = 0;
    }
    isValid = await this.validator({
        context: dc.context,
        recognized: recognized,
        state: state.state,
        options: state.options,
        attemptCount: ++state.state['attemptCount']
    });
} else if (recognized.succeeded) {
    isValid = true;
}

// Return recognized value or re-prompt
if (isValid) {
    return await dc.endDialog(recognized.value);
} else {
    if (!dc.context.responded) {
        await this.onPrompt(dc.context, state.state, state.options, true);
    }

    return Dialog.EndOfTurn;
}

By default, the result of the internal recognition made by the prompt is the one that triggers the retry or the return of the result. In other words, if the recognition result fails, the prompt is shown N times.

To control the number of retries, it is required a validator function that allows to manage the attemptCount counter. For this purpose, aura-bot-common library provides a validator function: getRetriesValidator, to control the number of retries. For its use, it is necessary to send this function as a second parameters in the prompt:

// Create a prompt without retries:
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesValidator(0));

Note that this validation function (that the dialog developer can build on his own), gives total flexibility to modify parameters each time the user responds.

Choice prompts

The prompt type “choice” asks the user to choose from a list of options. In this situation, the prompt-recognizer tries to recognize the choice selected with the options provided. If there is no match, it executes the NLP recognition.

The process for executing a choice prompt is detailed below:

Declare the name of prompts to be used within the current dialog.

private promptsNames = {
    ACCESS_PERMISSION: 'access-permission',
    TERMS_AND_CONDITIONS: 'terms-and-conditions'
  };

Notify the parent dialog that a prompt (with a declared id) is to be used and set its style.

const connectPrompt = new ChoicePrompt(this.promptsNames.ACCESS_PERMISSION);
connectPrompt.style = ListStyle.heroCard;
super.addDialog(connectPrompt);

In a step of the waterfall dialog, define the prompt.

Create Choices:

// Choice options.
const choicesText: Choice[] = [
   {value: text1},
   {value: text2} ];
// Prompt with text.
const message: Partial<Activity> = MessageFactory.text('message');
const promptOptions: PromptOptions = {
   prompt: message,
   choices: ChoiceFactory.toChoices(choicesText)
};

Execute the prompt:

return await stepContext.prompt(this.promptsNames.ACCESS_PERMISSION, promptOptions);

An example to handle the result of the user’s action is shown below:

if (stepContext.result && stepContext.result.index === 0 ) {
 	// Save data
 	return await stepContext.next();
 } else {
 	// Cancel option
 	return await stepContext.endDialog();
 }

Use prompt values as commands

If the target is to provide as prompt options a series of commands to redirect to other dialogs, we can use the useValueAsCommand flag.

// create a list of intent commands to be used with the prompt
const actions = [
// REMARK: In this case, the trigger condition points to the same dialog, but it could point to ANY INTENT known to the bot,
// making it a versatile feature.
{ intent: 'intent.fake.something', entities: [{ entity: CommandChoices.FIRST_OPT, type: 'suggestion' }] },
{ intent: 'intent.fake.something2', entities: [{ entity: CommandChoices.SECOND_OPT, type: 'suggestion' }] }
];
const cardActions = CardFactory.actions(actions.map(a => {
    return {
      type: ActionTypes.ImBack,
      title: a.entities[0].entity,
      value: JSON.stringify(a)
     };
}));
const promptOptions: PromptOptions = { 
	choices: ChoiceFactory.toChoices(cardActions),                          
        prompt: 'This is an example of Choice prompt with command values', 
	validations: { useValueAsCommand: true } 
}; 
return await stepContext.prompt('ID_PROMPT', promptOptions);

Creating the prompt in this way, when the user selects one of the options, it automatically redirects to a new intent in the process of recognizing the user’s action, forcing the prompt dialog to be cleared when there is a match.

⚠️ If the option chosen is the None intent, the stack cleaning behavior remains the same as always with the non-default cases to break the prompt (See section Break prompt and NLP recognition) such as the flag of enableNone etc.

Use of prompts in bypass mode

In a dialog working in bypass mode, you can use prompts that can be created as usual in the dialog:

    public DEFAULT_RETRIES: number = 2;
    public promptsNames = {
        COMMAND_CHOICE_PROMPT: 'command-choice-prompt'
    };

    constructor(configuration: Configuration) {
        ....
        // adds the prompt dialog to the Dialogs Set
        this.customPrompt = new ChoicePrompt(this.promptsNames.COMMAND_CHOICE_PROMPT,
            PromptUtils.getRetriesValidator(this.DEFAULT_RETRIES));
        ...
    }

The prompt will be instantiated, when the bypass mode initializes.

    this.customPrompt = new ChoicePrompt(this.promptsNames.COMMAND_CHOICE_PROMPT, PromptUtils.getRetriesValidator(retries));
    // To change retries we need replace original dialog for prompt
    (this.dialogs as any).dialogs['command-choice-prompt'] = this.customPrompt;
    return await Bypass.initialize(
        context,
        parseFloat(timeoutMin),
        { value: '' },
        'test',
        BypassState.Bypass,
        closeWords
    );

The prompt can be sent to the user and its value retrieved in the dialog.

private async sendPrompt(stepContext: WaterfallStepContext): Promise<DialogTurnResult> {
        const choicesText: Choice[] = [
            { value: 'id-0001', action: { title: 'Option 1 (id-0001)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0002', action: { title: 'Option 2 (id-0002)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0003', action: { title: 'Option 3 (id-0003)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0004', action: { title: 'Option 4 (id-0004)', type: '', value: '' }, synonyms: [] },
            { value: 'id-0005', action: { title: 'Option 5 (id-0005)', type: '', value: '' }, synonyms: [] }
        ];

        const promptOptions: PromptOptions = {
            prompt: 'Hello, select one option: write the number, cardinal, ordinal or text',
            choices: ChoiceFactory.toChoices(choicesText)
        };
        return await stepContext.prompt(this.promptsNames.COMMAND_CHOICE_PROMPT, promptOptions);
    }

    private async fallbackStep(stepContext: WaterfallStepContext): Promise<DialogTurnResult> {
        await stepContext.context.sendActivity(`Option selected: ${stepContext.result.value}`);
        return await stepContext.endDialog();
    }

Data saving between Waterfall steps

getDataActiveDialog and setDataActiveDialog from DialogUtil in the aura-bot-common library are used to keep data between steps of a waterfall.

⚠️ If it is required to send data to another dialog, this method cannot be used.

The following example saves data in DATA_KEY as key: DialogUtils.setDataActiveDialog(stepContext, 'DATA_KEY', data);

In the dialog code, it should use the DialogUtils utility to recover those parameters with the key DATA_KEY:

const data: any = DialogUtils.getDataActiveDialog(stepContext, 'DATA_KEY'); (context.activeDialog.state[keyData] can be used as well directly.)

Read dialog settings

When in aura-bot flow the main-dialog has routed a dialog to be started, it is launched with dialogSetting parameters:
return await stepContext.beginDialog(idDialog, dialogSetting);

To receive configuration parameters when a dialog is started, the DialogUtils utility should be used to recover those parameters with the key options:
dialogSetting = DialogUtils.getDataActiveDialog(stepContext, 'options');

In the following example, the channel data is being routed:

{
   "name":"issues",
   "dialogs":[
      {
         "id":"issue-create",
         "suggestions":true,
         "triggerConditions":[
            {
               "intent":"intent.issue.repair",
               "contextFilters":[
                  {
                     "name":"Example redirect to greetings from issues",
                     "type":"type",
                     "conditions":"'1' eq '1'",
                     "true":{
                        "name":"Test",
                        "breakDialogExecution":true,
                        "breakFilterEval":true,
                        "redirectToIntent":"intent.common.greetings",
                        "suggestions":true
                     }
                  }
               ]
            }
         ]
      }
   ]
}

Conditions of contextFilter are always be fulfilled so intentResult will be “greetings” while originalIntent will be “issue” (if there is no contextFilter, intentResult would be “issue”). Therefore, this is the structure of dialogSetting:

Replacing a dialog

A dialog can replace another dialog by breaking its current flow. For this purpose, the command replaceDialog is used and it is necessary to know the identifier of the library and the dialog destination.

A basic example is shown below:

return await stepContext.replaceDialog(`${ID_LIBRARY}:${ID_DIALOG_DESTINATION}`);

If the destination dialog does not expect any dialogSettings, the above example would be valid.

If it is necessary for the destination dialog to receive data from the original dialog, the developer must include the appropriate instructions for sending and receiving the required parameters. However, in order to maintain consistency with the established protocol for sending dialogSettings from the main dialog, it is recommended to maintain id, originalIntent and intentResult structure.

Two case examples are shown below:

Case A: Simple dialog replacement:

const currentDialogSettigns = DialogUtils.getDataActiveDialog(stepContext, 'options');
const destinationDialogSettings =
      {
          id: ID_DIALOG_DESTINATION,
          originalIntent: currentDialogSettings.intentResult,
          intentResult: {intent: INTENT_DESTINATION},
          ...
          others :?
          ...
      }
return await stepContext.replaceDialog(`${ID_LIBRARY}:${ID_DIALOG_DESTINATION}`,destinationDialogSettigns );

In this example, destinationDialogSettings can be optional and is not sent to Handover (in fact, real Handover dialog is not using these settings).

Case B: Replace a dialog where there is a contextFilter In this case, if the dialog needs to replace itself, it is necessary to send the same dialogSettings that was sent by the main dialog:

const currentDialogSettings = DialogUtils.getDataActiveDialog(stepContext, 'options');
return await stepContext.replaceDialog(`${ID_LIBRARY}:${ID_DIALOG_DESTINATION}`,currentDialogSettings );

Data saving in the same conversation

auraDataAccessor can be the second parameter of the constructor. The command auraDataAccessor?: auraDataAccessor allows accessing to the conversation data, certain user data, etc.

auraDataAccessor has the following schema:

export interface AuraDataAccessor {
    conversationDataAccessor: StatePropertyAccessor;
    dialogStateAccessor: StatePropertyAccessor<DialogState>;
    userAuthDataAccessor: StatePropertyAccessor;
    userDataDataAccessor: StatePropertyAccessor;

Logs management

For a proper analysis of the code, it is very important to use logs correctly. The field corr refers to the correlator, which has to be set in all cases in order to follow up the requests.

The correlator can be retrieved through a functionality of the commons library: ContextUtils.getCorrelator(context). It is necessary to send the current context (in a Waterfall step, it should be stepContext.context).

this.logger.info({
     msg: 'Message',
     corr: ContextUtils.getCorrelator(context)
});

There are cases in which the correlator does not exist because aura-bot is in start process, configuration, make-up, etc. In these cases, the assigned field is no-correlator. In debug and info mode, it can include new fields in order to organize and improve the data.

An example is shown below:

this.logger.debug({
     msg: 'Cognitive Services API response',
     corr: ContextUtils.getCorrelator(context),
     NEW_FIELD: value
});

The following example is useful to write error logs:

logger.error({ 
      corr: ContextUtils.getCorrelator(context), 
      error: error.message, 
      msg: 'Server cannot be closed', 
      stck: error 
});

Docs:

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

Building Aura response in RCS channel

Building Aura response for a use case in the RCS channel has certain particularities due to the limitations of this channel

Introduction

When developing a use case, you should follow the general guidelines for building Aura response, which are common for all channels.

However, for RCS channel, certain specific steps must be carried out regarding rendering limitation of this channel and the configuration of the necessary attachments.

Sending messages to clients

Due to the special format of RCS messages and to avoid the extra complexity and maintainability of a transformation in aura-bridge between Directline messages and RCS messages, a new attachment type has been defined to send directly the payload of RCS messages in the activity. This payload will be sent directly to RCS by aura-bridge without any transformation.

Furthermore, the communication between aura-bridge and aura-bot is done using channelData V3, so dialogs should be implemented following the indications in the document Guidelines for creating/migrating a dialog to channelData v3.

Sending a text message

To send a simple text message, send an activity as shown below:

const dialogSettings = DialogUtils.getDataActiveDialog(stepContext, 'options');
const intentResult = dialogSettings?.intentResult;

await stepContext.context.sendActivity({
    text: 'Text doesn\'t matter',
    channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
    attachments: [{
        contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
            'contentMessage': {
                'text': 'Hello, world!'
            }
        }
    }]
});

In the previous example, the text “Hello, world!” will be sent to te user. The text inside the activity’s text field will be ignored.

There is only one special case when the text field of the activity is used to create the message: when the attachment with type application/vnd.telefonica.aura.rcs.message does not exist in a message of an RCS channel. But this case is reserved for error messages or other special situations. By default, text messages should be created with the necessary attachment.

Sending actions

You can send multiple types of actions to the user. All are defined in RCS Documentation.

All these actions have the field postbackData that will be returned to the bot as a text message when the user interacts and the dialog should know how to handle it.

You can set postbackData as a text auraCommand to handle it in a different dialog.

More info in Handling user messages in RCS channel

Sending a dial action

await stepContext.context.sendActivity({
    text: 'Text doesn\'t matter',
    channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
    attachments: [{
        contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
            'contentMessage': {
                'text': 'Call technical service',
                'suggestions': [
                    {
                        'action': {
                            'text': 'Call us!',
                            'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"call"}]}',
                            'fallbackUrl': 'https://www.google.com/contact/',
                            'dialAction': {
                                'phoneNumber': '+66666666666'
                            }
                        }
                    }
                ]
            }
        }
    }]
});

Sending a location action

    await stepContext.context.sendActivity({
    text: 'Text doesn\'t matter',
    channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
    attachments: [{
                    contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
                        'contentMessage': {
                            'text': 'Location message',
                            'suggestions': [
                                {
                                    'action': {
                                        'text': 'View map',
                                        'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"location"}]}',
                                        'fallbackUrl': 'https://www.google.com/maps/place/40%C2%B021\'39.5%22N+4%C2%B020\'01.8%22W/@40.3609722,-4.3338333,17z',
                                        'viewLocationAction': {
                                            'latLong': {
                                                'latitude': '40.36085110',
                                                'longitude': '-4.33394257'
                                            },
                                            'label': 'Pelayos de la presa, pedacito de cielo'
                                        }
                                    }
                                }
                            ]
                        }
                    }
                }]
    });

Sending an URL

    await stepContext.context.sendActivity({
    text: 'Text doesn\'t matter',
    channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
    attachments: [{
                    contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
                        'contentMessage': {
                            'text': 'Url message',
                            'suggestions': [
                                {
                                    'action': {
                                        'text': 'Open Google',
                                        'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"el link"}]}',
                                        'openUrlAction': {
                                            'url': 'https://www.google.com'
                                        }
                                    }
                                }
                            ]
                        }
                    }
                }]
    });

Sending a prompt

Here is an example of how to send a prompt to the user in RCS.

Due to the characteristics of this channel, you need to define the prompt options twice: as choices of the prompt and as suggestion buttons for the user.

As you can see, the choices values are set in choices and also as suggestions in the attachment. The value in the postbackData must be the same as the one set in the choices, because it will be the value returned when the button is clicked. The text field of the reply object is the text showed to the user and can have any value.

        const dialogSettings = DialogUtils.getDataActiveDialog(stepContext, 'options');
        const intentResult = dialogSettings?.intentResult;

        const choicesText: Choice[] = [
            { value: 'Accept', synonyms: ['ok', 'yes'] },
            { value: 'Deny', synonyms: ['no'] }];
        const promptOptions: PromptOptions = {
            prompt: {
                text: 'Text doesn\'t matter',
                channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
                attachments: [{
                    contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
                        'contentMessage': {
                            'text': 'Hello, write one option or write the associated number',
                            'suggestions': []
                        }
                    }
                }]
            },
            choices: ChoiceFactory.toChoices(choicesText)
        };
        choicesText.forEach((choice, index) => {
            (promptOptions.prompt as Partial<Activity>).attachments[0].content.contentMessage.suggestions.push(
                {
                    'reply': {
                        'text': choice.value,
                        'postbackData': choice.value
                    }
                });
        });
        return await stepContext.prompt(this.promptsNames.COMMAND_CHOICE_PROMPT, promptOptions);

Sending rich cards

Rich cards allows you to send more complex messages to the user. All the info about rich cards in RCS can be found here

    await stepContext.context.sendActivity({
    text: 'Text doesn\'t matter',
    channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
    attachments: [{
                    contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
                        'contentMessage': {
                            'richCard': {
                                'standaloneCard': {
                                    'thumbnailImageAlignment': 'RIGHT',
                                    'cardOrientation': 'VERTICAL',
                                    'cardContent': {
                                        'title': 'Hello, world!',
                                        'description': 'RBM is awesome!',
                                        'media': {
                                            'height': 'TALL',
                                            'contentInfo': {
                                                'fileUrl': 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
                                                'forceRefresh': 'false'
                                            }
                                        },
                                        'suggestions': [
                                            {
                                                'reply': {
                                                    'text': 'Suggestion #1',
                                                    'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"suggestion 1"}]}',
                                                }
                                            },
                                            {
                                                'reply': {
                                                    'text': 'Suggestion #2',
                                                    'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"suggestion 2"}]}',
                                                }
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }]
    });

Sending carousels

Carousels are a special type of rich cards. You can find more info here

    await stepContext.context.sendActivity({
    text: 'Text doesn\'t matter',
    channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, corr),
    attachments: [{
                    contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
                        'contentMessage': {
                            'richCard': {
                                'carouselCard': {
                                    'cardWidth': 'MEDIUM',
                                    'cardContents': [
                                        {
                                            'title': 'Card #1',
                                            'description': 'The description for card #1',
                                            'suggestions': [
                                                {
                                                    'reply': {
                                                        'text': 'Card #1',
                                                        'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"card 1"}]}',
                                                    }
                                                }
                                            ],
                                            'media': {
                                                'height': 'MEDIUM',
                                                'contentInfo': {
                                                    'fileUrl': 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
                                                    'forceRefresh': 'false'
                                                }
                                            }
                                        },
                                        {
                                            'title': 'Card #2',
                                            'description': 'The description for card #2',
                                            'suggestions': [
                                                {
                                                    'reply': {
                                                        'text': 'Card #2',
                                                        'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"card 2"}]}',
                                                    }
                                                }
                                            ],
                                            'media': {
                                                'height': 'MEDIUM',
                                                'contentInfo': {
                                                    'fileUrl': 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
                                                    'forceRefresh': 'false'
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }]
    });

Docs:

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

Building Aura response in WhatsApp channel

Building Aura response for a use case in the WhatsApp channel has certain particularities due to the limitations of WhatsApp channels

Introduction

When developing a use case, you should follow the general guidelines for building Aura response, which are common for all channels.

However, for WhatsApp channel, certain specific steps must be carried out regarding POEditor resources, rendering limitation of WhatsApp channels and the configuration of the Markdown type to be used in the response.

Specific POEditor resources for WhatsApp channel

Take into account that the WhatsApp channel requires specific POEditor resources corresponding to aura-bridge errors and to the onboarding, authentication and handover dialogs.

Therefore, you should edit the texts corresponding to these resources.

Resources for Aura bridge errors

The locales corresponding to aura-bridge errors can be checked here, with an example text for Spain: https://github.com/Telefonica/aura-bridge/blob/master/locale/es-es.json

There are specific resources for WhatsApp (WA) or general resources for all channels.

Resources for WhatsApp dialogs

Likewise, aura-bot has specific resources for the onboarding, authentication and handover dialogs.

At this stage, you should edit the texts associated to these resources, which are included in their corresponding documents:

WhatsApp dialog	POEditor resources documentation
onboarding-whatsapp-dialog	Onboarding in WhatsApp
whatsapp-otp-login-dialog	SMS-OTP authentication in WhatsApp
handover-dialog	Handover in WhatsApp

Resources for buttons and lists

Find specific resources for WhatsApp interactive messages (buttons and links) in Use of interactive messages in WhatsApp graphical interface.

Rendering in WhatsApp channels

WhatsApp is configured in Aura as "output_message_format": "simple". That means that aura-bot can only return text or Hero Cards components.

Aura and WhatsApp speak different languages, so they cannot communicate directly and the bridge acts as a translator between them. Therefore, at this stage, it is required to render all the components to be included in Aura response taking into account the limitations and constraints for this channel.

Rendering Aura response components

For every component of Aura response, check the document Rendering Aura response components in WhatsApp to know how aura-bridge converts them to be shown in WhatsApp and the limitations and constraints for this channel.

Configuration of Markdown type in the response

By default, use cases in WhatsApp build the response using WhatsApp-specific markdown as aura-bridge converts the standard Markdown (Direct Line messages) into WhatsApp markdown when a use case sends an answer containing this language.

However, OBs can decide if the conversion should or should not take place, so aura-bridge would/would not make the conversion before sending the message to the channel.

This modification in the Markdown format is available for WhatsApp-type channels (currently, WhatsApp) and can be done at two levels: a. Channel level b. Use case dialog level

The succeeding sections show the specific processes for this configuration.

Modifications of Markdown format at channel level

The default configuration of aura-bridge, that converts the standard Markdown (text received from Direct Line message) into WA-specific Markdown, can be modified at channel level, so the response to the user will be provided in WhatsApp Markdown format for a specific channel.

For this purpose, constructors must use the whatsapp field in the channels’ configuration file. The interface is as follows:

export interface WhatsAppModel {
    ...
    /**
     * Indicates whether the texts of each of the messages received must be converted to the WhatsApp markdown format.
     * Default: true
     */
    textConvert?: boolean;
}

It is possible to disable text conversion to WhatsApp markdown format setting the value of the whatsapp.textConvert to false (by default, it is true):

{
    "name": "whatsapp",
    ...
    "whatsapp": {
        "textConvert": false        // Do not convert
    },
}

⚠️ Be aware of the behavior:

In this case, the dialog will follow the channel’s behavior.
However, if the dialog is also configured not to do the conversion (see next section), then this configuration will take precedence over the channel configuration.

Modification of Markdown format at dialog level

The default configuration of aura-bridge, that converts the standard Markdown Markdown (text received from Direct Line message) into WA-specific Markdown, can be modified at use case (dialog) level, so the response to the user will be provided in WhatsApp Markdown format for a specific use case.

For this purpose, constructors may change the activity using the payload model > textConvert field.

The interface is as follows:

export interface Whatsapp {
    ...

    /**
     * Indicates whether the texts of each of the messages received must be converted to the WhatsApp markdown format.
     * Default: true
     */
    textConvert?: boolean;
}

To avoid the text conversion to WhatsApp markdown format, constructors can set the value of the textConvert field to false (by default, it is true):

{
    type: 'message',
    ...
    channelData: {
        payload: {
            bridge: {
                whatsapp: {
                    textConvert: false      // Do not convert
                }
            }
        }
    }
}

⚠️ Remember that the dialog configuration will take precedence over the channel configuration.

Docs:

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

Build the use case logic: use cases development over Aura Bot

Guidelines for every step included in the development of a use case over Aura Bot, from building the dialog that models the conversational flow with the user and fetches the required data to its deployment in order to make the experience available for Aura users

Process at a glance

Bot
start-up

First time with aura-bot?
. Install aura-bot
. Configure aura-bot

Develop uc logic

. Develop an aura-bot library/dialog
. Test the dialog
. Build the response for Aura users

Package and
test use case

. Package the developed use case
. Test locally to evaluate its performance

Deploy
use case

. Make certain key checks before deployment
. Finally, deploy the developed use case

Use cases in WhatsApp

. Follow the general guidelines, but also check the specific extra steps

Introduction

The documents included in this section show the detailed processes for the development of use cases over aura-bot, with guidelines for all the feasible scenarios that can appear at this stage.

The following figure schematically shows the general workflow for the development of a use case over aura-bot.

Docs:

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

Define and configure agent

Description of the process for defining a new agent in ATRIA

Introduction

The first step for the creation of a new agent in ATRIA includes the definition of the agent. This is done by extending the BaseAgent class, in charge of creating the basic structure for all the agents to be developed and the management of its configuration.

Base class

The BaseAgent class provides the necessary functionality to initialize agent, manage configurations and interact with the agent package.

Access here the BaseAgent class in the Github repository.

The ATRIA agent-server uses this class to identify all the agents of the agent package coming from the BaseAgent.
This class promotes functionalities to initialize and build the agent.

Build agent

To build an agent it is necessary to extend this base class and, at least, extend these functionalities, according to the specific goals assigned to the agent.

get_class_ref: This method is used to get the class reference of the agent. It is used to identify the agent in the system.
build: This method is used to build the agent. It is used to set up the necessary configurations and to get everything required to initialize the agent.
__call__: This method is used to call the agent. It is used to execute the agent’s functionality.
initialize: This method is optional and used to initialize the agent. For example, it can be used to set up the agent’s state or to load any necessary data.

Configuration and information

The BaseAgent class provides a way to manage the agent’s configuration and information.

Information

The agent information is generated during the agent creation stage and can be accessed through the info field. It contains the following fields:

identifier: Unique identifier of the agent. This value corresponds to the class_ref of the agent.
name: Name of the agent. This value corresponds to the name of the agent coming from API.
deployment_name: Name of the agent deployment used to identify the agent environment that corresponds to the agent.
base_name : Base name of the agent used to identify the type agent. This value corresponds to the name of the agent class.
version : Version of the agent used to identify the version agent. This value corresponds to the version of the agent package installed.

Configuration

The agent configuration is generated during the agent creation stage from the aura-configuration-api, within the API agentBase.configuration field.

Here is an example.

 {
      "id": "XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "test-agent",
      "deploymentName": "test-deployment-agent",
      "description": "A test agent",
      "communication": {
          "communicationType": "http"
      },
      "agentBase": {
          "name": "test-agent",
          "configuration": {
            "test": "test_value",
            "url": "http://localhost:8000"
          }
      }
  }

The entire content of this field is inserted into the agent under creation as a dictionary in the config field of the agent.

To obtain the configuration, access this config field as shown in the example below, where we want to obtain the test field within the agent’s configuration.
The use of the config will always be to fetch the information and not to store it between requests, as this config can be updated on the fly without the need to restart the component, so the config is read on each request.

test_value = self.config.get("test", None)

All this configuration is at agent level, but there are also configuration values at environment level. To obtain this environment configuration, use the command below:

test_value = os.getenv("TEST_ENV_VAR")

Docs:

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

Guidelines for skills development

Description of processes and tools for the development of skills to be subsequently connected to Aura

Introduction

The process for the development of a skill that will be subsequently connected to Aura is different, depending on the type of skill.

In Phase 1, OBs are able to develop skills outside Aura cluster:

Using a technology compatible with Microsoft Bot Framework (Direct Line protocol), for example, with Microsoft composer.
Third-party bots, defined as bots that are not part of the Microsoft ecosystem. The development of external bots with different technologies for their subsequent integration into Aura includes two main stages that must be carried out by constructors:
- The bot development itself, with the preferred technology (Google Assistant, Teneo, etc).
- The development of a third-party adapter, required for the bot to communicate with Aura Root. This adapter must be able to convert requests to be sent to the external bot, and the other way around with answers.

In this framework, there is an available tool that eases the development and subsequent testing of the skill: aura minigroot. The already existing aura minibot works now jointly with aura minigroot.

Access MiniGroot skill connection and Aura Minibot user guide

Docs:

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

Guidelines for the generation of Grammars in Unitex

Guidelines and best practices for working with Unitex for the generation of the Grammars to be included in the NLP model.

General guidelines

Grammars is an Aura NLP stage that has its own path, files and configuration required to be included in the NLP model.

Firstly, if your pipeline contains the Grammar stage, you need to work with Unitex Gramlab and Grape NLP, which are included in the NLP Virtual Machine.

After that, linguists can proceed to create the grammars associated to the new use case. This process will be similar for global and local grammars.

The intent, entities and utterances defined for the new use case must be considered. A representative set of utterances will be selected and represented in Unitex through the creation of connected boxes that will contain, from left to right, different options for expressing each token of the selected utterances. The combination of different connected boxes provides a full variability of utterances to be recognized.

It is necessary to bear in mind that grammar engine only provides an exact recognition of utterances previously integrated in the model. Therefore, it is necessary to build up a rich and realistic utterance database to cover all the representative users’ utterances for a given use case.

Once the grammars have been developed in Unitex, the grammar engine Grape NLP goes through the grammar from the beginning (left side of the graph) and compares box by box the user’s utterance with the grammar to evaluate the matching.

The output will be a set of labels together with a start and end index.

Intents and entities tagging

Tag an intent in the grammar interface

In order to tag an intent in a grammar graph, a box previous to the closing box of the graph should be created with the following information and format:

<E>/<intent.[intent_name]/>

Tag an entity in the grammar interface

Two separate boxes need to be created: one before and one after the entity values.
We need two entity tags because we need to wrap the entity values in order to know its position in the user’s utterance.
Opening entity tag should have the following information and format:
```
<E>/<ent.[entity_name]> 
```
Closing entity tag requires the following information and format:
```
<E>/</ent.[entity_name]>
```
Consider the difference between the opening and closing entity tag and remember that the entity tags need to be included within the entity graph and not outside of it.

Best practices for graphs generation

We highly recommend you the webinar Implementing new use cases: Grammar guidelines.
The graphs must be as visually clear as possible.
Avoid crosslines.
The verbal graphs should be vertically aligned and the arrows connecting boxes should be horizontally aligned.
Be careful when using too much optionality (“Epsilon” symbol), this may lead the grammar to recognize unwanted strings, collisions between UCs, etc.
All graphs should have an appropriate size not to leave info/boxes out of the them.
Try not to repeat the same box structure several times. Try to reuse it for different paths or to create a subgraph that can be reused anywhere in the intent axiom. Hence, avoid creating two or more paths recognizing the same input.
Use comments if needed to clarify, for instance, if a path has some limitations due to potential conflicts with other UCs or just as explanatory notes of what a path is contemplating. For creating a comment within a graph, create a box and do not connect it to any other box. This way, you will see that the characters of comment message appear in red colour.
Avoid leaving empty boxes in any graph.
Avoid typos within the boxes info.
The opening and closing entity tags used for wrapping the entity values should be contemplated in the entity graph and not outside of it.
Make sure the intent and entity tags have been properly included.
When adding prepositions and articles in boxes, put them separately. That is, create a box for the prepositions and another one for the articles.
The circumstantial complements (e.g., time, location, manner…) are optional on many occasions regardless of whether they are in initial, middle or final position.
No graph must recognize the “Epsilon” symbol:
```
 <E>
```
So in case of optional subgraphs, the optionality should be in the graph where it is called and not in the subgraph.
If the grammar makes use of the NER dictionaries to do the matching value > canon > label, the values contemplated in the different dictionaries should be also contemplated in the entity graphs of the grammar for the matching process to be successful.
- It is crucial to consider here that the grammar values contemplated in the entity graph should be normalized (same process as the normalization pipeline carries out except for the normalization of upper-case characters) in order to be recognized.
- That is, if a value in the dictionaries is ‘Mr. Robot’, since the normalization pipeline erases punctuation marks, the value that should be included in the entity graph should be ‘Mr Robot’.
There are special symbols that have specific meaning for the grammar and should be escaped (to check these symbols go to “Encoding of special characters in the graph editor” section of the Unitex Gram Lab official documentation).
An example of a special character would be “+” that needs to be escaped by using ““ (See figure below).
It is highly recommendable to compile the grammar before pushing changes into the Pull Request. This way, the NLP developer will see if there is any error in the call to the subgraphs, if the grammar recognizes an empty path (the grammar recognizes: " “) or if there is any corrupt file.
When compiling the grammar, some files are generated. These files have different extensions (.fst2, .snt, .diff) and should be avoided. Thus, the NLP developer should erase them locally before committing further changes into the PR.
For main verbs or list of keywords, create another graph.
Try to reuse basic structures (grammar block) from one graph to another.
Try to avoid ungrammatical paths if possible.
If one graph gets too complex, try to split it into smaller blocks/subgraphs.

Best practices for the generation of .grf files

Create as many folders as existing domains/intents.

Graphs

Call axiom.grf to the main graph of the whole grammar (general graph that calls to the different domains).
Generate another axiom.grf file in the subfolder of each specific domain, which will be the main graph for this domain (graph that calls to the UCs related to that domain).
Generate another axiom.grf file for each use case/intent. Remember that, if different subgraphs are created to contemplate different structures or entity combinations for a given UC, the intent tag should be found in this general UC/intent axiom and not in the individual subgraphs.

Domain folder

The name of the domain folder should be identical to the name of the corresponding domain.
This way, when opening the main graph of the whole grammar, one could quickly see the domains that have, at least, some UC developed through the grammar engine. Make sure when including a new domain to make the proper call to it in the main axiom of the whole grammar.

Intent folder

The name of the intent folder should contemplate the name of the corresponding intent.
For example: If the intent name is intent.common.greetings, the intent folder name would be greetings.
If a given intent has different sub-use cases or the intent is divided into different graphs according to different linguistic structures/entities combination, the intent tag should be only tagged once in the main axiom of the use case and not in each of the different subgraphs.
Make sure when including a new intent to make the proper call to it in the domain axiom.

Entity graphs

The entity graphs should have the name of the corresponding entity name, that is, if an entity name is ent.device_tv, the name of the graph in the grammar folder should be ent.device_tv.grf.
If an entity is only used in one use case/intent, the entity graph should be located in the intent folder.
Otherwise, if an entity is used in different intents/UCs of the same domain, the entity graph should be located in the main folder of the domain.
If an entity is used in different domains, the entity graph should be in the main folder of the whole grammar.

Verbal structure and nomenclature

Introduction

Verbal graphs need to be adapted based on the target language the NLP developer is working with.

The following verbal forms and tenses have been provided in Spanish as illustrative examples because the Spanish language varies morphologically depending on the person/number and tense info.

Nomenclature of auxiliary verbs:
- Auxiliary verbs: They serve, among other things, to form the compound tenses, the progressive forms, the passive voice, as well as negations and questions (e.g., “I would like to eat an apple”).
- Main/Full verbs: They add meaning to the sentence and are essential for understanding the statement (e.g., “I eat two apples every morning”).

To this end, the NLP team has been working on an efficient structure and nomenclature to have them contemplated in the grammar.

Auxiliary verbs

aux_W: auxiliary verb + infinitive tense

It contemplates all the possible auxiliary verbs that can be found before a verb in infinitive tense.

This graph should be always optional since the infinitive tense without the auxiliary verb is also acceptable in linguistic terms (e.g., “I want to check my agenda” & “Check my agenda” are both linguistically correct).

aux_Y: auxiliary expressions/verbs + imperative tense

aux_Y2s: second person singular in imperative tense.
aux_Y3s: third person singular in imperative tense.
aux_Y2p: second person plural in imperative tense.
aux_Y3p: third person plural in imperative tense.

All these graphs contain possible auxiliary expressions that may be found before verbs in imperative tense.

These graphs should be also optional as the verbs in this tense can be also found in isolation (e.g., “Go and bring me some water” & “Bring me some water”). All these graphs should be found within the graph containing all imperative tenses of a given verb (e.g., verb_Y.grf -> buy_Y.grf).

aux_SQT: auxiliary verb + present/past imperfect subjunctive tense

It contains all possible expressions that can be found before a verb in present imperfect subjunctive tense (S) and past imperfect subjunctive tense (QT).

This graph should be always mandatory in these two tenses as the structure “I would like you to bring me some water” vs. “I like you to bring me some water” would be agrammatical without the modal verb.

Main verbs

This graph is used for ambivalent verbs that could work both as auxiliary and main/full verbs.

When this graph is used, all these verbs are conceived as being main/full verbs and thus do not need to be accompanied by another verb but by a complement in the form of a noun (e.g., “I want some water” vs. “I want to drink some water”).

Verbal graphs

The names of the verbal graphs should be in English. This also applies to the name of the domain, intent, keywords and complement graphs.
Before creating any verbal graph, make sure it is not repeated, that is, it is not already contemplated in any other of the grammar UCs. If a given verb is only used in a particular UC, place the verbal graphs within the folder of the UC. If a verb is shared by several UCs of the same domain, place the verbal graph at the domain folder level.
If, on the other hand, a given verb is used by UCs belonging to different domains, place the verbal graphs in the folder of the whole grammar.
If you create different verbal subgraphs for different verbal tenses, make sure you include all the verbs in each tense. The basic verbal tenses included for each verb are:

In case the developer needs to contemplate more verbal tenses, please consult the section “Common inflectional codes” in Unitex Gram Lab official documentation.

[verb]_main_graph structure

To ease the grammar development process, we propose a common structure for all verbs.

The name of the verbal graph would be [verb]_main_graph.grf and would have the following structure:

As it can be appreciated in the example, some pronouns have been added between aux_SQT and the verbal boxes for those tenses. This also happens before P3s/p, P2s and C2s verbal boxes.
These pronouns are needed for sentences such as: “Quiero que me compres este vuelo” (“I want you to buy me this flight”). Besides, the interrogative particle “cómo” has been added before aux_W and before P1s/p tenses for questions such as “¿Cómo puedo comprar este ticket?” (“How can I buy this ticket”) and “¿Cómo compro este ticket?” (“How do I buy this ticket”).

In case the clitic forms of verbs are needed, create a separate graph for them. For this, create a verbal graph called [verb]_clitic_forms.grf. As in the previous example, some pronouns have been included in some of the paths, but the main difference here would be that the boxes containing the clitic pronouns have been included in a mandatory way.

As seen in the figure, this graph would recognize sentences such as: “Quiero que me lo compres” (“I want you to buy it for me”).

Guidelines for testing Grammars in Unitex

There are two alternative ways of testing the grammars generated with Unitex:

1. Testing grammars using the Unitex interface

Useful for checking the potential overlaps among the different use cases developed through the grammar engine.

For this purpose, a .txt file should be created with the testing statements (sentences, phrases or isolated words) to be tested (each one on a different text line).

Keep in mind that when testing the grammar in the Unitex interface, the testing statements are not going to be processed with the normalization pipeline and, thus, must consider capitalization, accentuation marks, etc.

Afterwards, the following instructions should be carried out:

Open the Unitex interface and go to the menu found in the upper section of the interface.
Click on “Text > Open” and open the .txt previously created (say “OK” to Process Text).
Once the .txt file is selected, go to “Text > Locate Pattern” and a window will pop up in which it is required to select the graph to be used to process the testing examples. The “Merge with input text option” should be also selected to see the intent and entity tags.
Besides, we need to select the “Activate debug mode option” to see the paths activated in each of the testing examples as well as the “Longest matches option” to replicate how the system works.
Click on “Search” and another window will pop up with the results.

If all the provided examples have obtained the expected intent, that means that the grammar engine has the expected behaviour.

2. Testing grammars through run_local_pipeline.sh scripts

The second option would be to launch queries through the run_local_pipeline.sh script to validate their intent assignment (remember that you must previously execute the build_local.sh script in order to train the pipeline).

Since the grammar engine is deterministic, based on the score (confidence) obtained, it is possible to know whether an utterance has been solved by CLU or by the grammar engine:

Utterances detected by the grammar module obtain a score of 1.0
The scores of utterances detected by CLU are float numbers between 0 and 1 (e.g. 0.98, 0.65…).

This testing option is the most recommendable one since this way we can see the faithful output of how the system works end-to-end.

Docs:

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

Handling user messages in RCS channel

The current document includes the guidelines for handling different types of messages in the RSC channel.

Handling user button responses

Some messages received from RCS channels have a particular behavior and some data is returned to the dialog in a new field of the channelData: channelData.payload.suggestionResponse.

Here is an example of a user response of this type:

{
    "type": "message",
    "id": "d152aee9-1aaa-5b54-95a5-79352eee2e45|MxRCKxirowTtaiNb8-REy9TA",
    "channelId": "f7fd1021-41cd-588a-a461-387cc24be225",
    "from": {
        "id": "34659949469",
        "name": "javiagent_crbwyhqz_agent@rbm.goog"
    },
    "conversation": {
        "id": "c0709653-45f7-4fca-9808-3702d11fc346"
    },
    "channelData": {
        "payload": {
            "suggestionResponse": {
                "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"card 1\\"}]}",
                "text": "Card #1",
                "type": "REPLY"
            },
            "bridge": {
                "channelId": "f7fd1021-41cd-588a-a461-387cc24be225"
            },
            "auraGroot": {
                "channelConversationId": "d152aee9-1aaa-5b54-95a5-79352eee2e45",
                "channelId": "f7fd1021-41cd-588a-a461-387cc24be225"
            }
        },
        "version": "3",
        "appContext": {
            "channel": {
                "modality": "text",
                "id": "f7fd1021-41cd-588a-a461-387cc24be225"
            },
            "timestamp": "2024-10-04T16:36:55+02:00",
            "timezone": "Europe/Madrid"
        },
        "correlator": "1be1b360-8cc4-4a4d-845b-bebb47869afd"
    },
    "text": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"card 1\\"}]}",
    "serviceUrl": "http://localhost:8080/api/skills",
    "relatesTo": {
        "serviceUrl": "http://localhost:8045/aura-services/javiagent",
        "activityId": "d152aee9-1aaa-5b54-95a5-79352eee2e45|MxRCKxirowTtaiNb8-REy9TA",
        "channelId": "f7fd1021-41cd-588a-a461-387cc24be225",
        "conversation": {
            "id": "d152aee9-1aaa-5b54-95a5-79352eee2e45"
        },
        "bot": null
    },
    "recipient": {
        "role": "skill"
    },
    "callerId": "urn:botframework:aadappid:3837ac07-50e0-4d4e-993b-1bda1349f25a",
    "locale": "es-cr"
}

The value of text and postbackData was set by the dialog when the card was sent, you can find more info in building Aura response

Handling suggestion responses

Buttons in cards, prompts or suggestions, return a REPLY response as the following suggestionResponse:

"suggestionResponse": {
    "postbackData": "Rock",
    "text": "Rock",
    "type": "REPLY"
}

If prompts are created as specified in building Aura response, they will be handled properly without any extra steps, because postbackData will be the text field of the activity and will be recognized by the prompt as an option.

Handling actions responses

Actions return an ACTION response as the following ones:

"suggestionResponse": {
    "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"la ubicación\\"}]}",
    "text": "View map",
    "type": "ACTION"
}

"suggestionResponse": {
    "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"llamar\\"}]}",
    "text": "Call",
    "type": "ACTION"
}

Ignoring responses

Every button sent to the user must have the postbackData field included:

            'contentMessage': {
                'text': 'Call technical service',
                'suggestions': [
                    {
                        'action': {
                            'text': 'Call us!',
                            'postbackData': '{"intent": "intent.factotum-test.rcs-formats","entities":[{"type":"type","entity":"postback"},{"type":"data","entity":"call"}]}',
                            'fallbackUrl': 'https://www.google.com/contact/',
                            'dialAction': {
                                'phoneNumber': '+66666666666'
                            }
                        }
                    }
                ]
            }

And this postbackData will be returned as a message to aura-bot when the user clicks the button. If you want to ignore this message or only write a log, you should implement a specific dialog to handle these actions and send every action response to this dialog with an aura-command:

{
                    contentType: 'application/vnd.telefonica.aura.rcs.message', content: {
                        'contentMessage': {
                            'text': 'Location message',
                            'suggestions': [
                                {
                                    'action': {
                                        'text': 'View map',
                                        'postbackData': '{"intent": "intent.ignore-user-postback.example-dialog","entities":[]}',
                                        'fallbackUrl': 'https://www.google.com/maps/place/40%C2%B021\'39.5%22N+4%C2%B020\'01.8%22W/@40.3609722,-4.3338333,17z',
                                        'viewLocationAction': {
                                            'latLong': {
                                                'latitude': '40.36085110',
                                                'longitude': '-4.33394257'
                                            },
                                            'label': 'Pelayos de la presa, pedacito de cielo'
                                        }
                                    }
                                }
                            ]
                        }
                    }
                }

Docs:

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

Logical connectors

Introduction

Connectors are components that connect different NLP stages and control the flow of the pipeline. Specifically, logical connectors use the logical connectives to combine different stages.

They can be classified in four main groups:

Competitive connectors

HigherScorePipeline

Description

Two or more stages competing in a parallel way, in which the result of the stage providing the higher score is selected.

Path

auracog_pipelines.pipelines.joint.competitives.HigherScorePipeline

Configuration

No configuration is required

Conditional connectors

Stages are strung together and executed in a specific way depending on the result of the boolean operators and/or/not.

There are three different types of conditionals connectors, whose result is shown in the figure below.

AndPipeline

Description

This connector is used if all the input conditions must be met in order to have the output true (see figure above).

Path

auracog_pipelines.pipelines.joint.conditionals.AndPipeline

Configuration

No configuration is required

OrPipeline

Description

This connector is used to express that, as long as one out of two or more conditions are met, the value for the output is true (see figure above).

Path

auracog_pipelines.pipelines.joint.conditionals.OrPipeline

Configuration

No configuration is required

NotPipeline

Description

This connector is used to reverse the input value from true to false and from false to true (see figure above).

Path

auracog_pipelines.pipelines.joint.conditionals.NotPipeline

Configuration

No configuration is required

Boolean Connectors

FalsePipeline

Description

The purpose of this connector is to execute in sequential order the stages that the connector contains and to return the status false. This connector ignores the status of the different stages which are contained.

Path

auracog_pipelines.pipelines.joint.conditionals.FalsePipeline

Configuration

No configuration is required.

An example of how to integrate the connector in a pipeline is shown below:

{
  "initial_node_id": "FalseBooleanPipeline",
  "elements": {
    "FalseBooleanPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.joint.booleans.FalsePipeline"
    },
      "type": "stage",
    }
  },
  "links": {
    "FalseBooleanPipeline": [
    ]
  }
}

TruePipeline

Description

The purpose of this connector is to execute in sequential order the stages that the connector contains and to return the status true. This connector ignores the status of the different stages which are contained.

Path

auracog_pipelines.pipelines.joint.conditionals.TruePipeline

Configuration

No configuration is required.

An example of how to integrate the connector in a pipeline is shown below:

{
  "initial_node_id": "FalseBooleanPipeline",
  "elements": {
    "TrueBooleanPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.joint.booleans.TruePipeline"
    },
      "type": "stage",
    }
  },
  "links": {
    "TrueBooleanPipeline": [
    ]
  }
}

Sequential connectors

These connectors work as follows: Stage B input is the output of its preceding stage A, with stage B output the result of summing both stages result.

The way the different stages are connected defines how the interactions between them are carried out. For example, two or more stages can run in a simultaneous competitive way, in which the winner is the stage with higher score or stages can be executed in a sequentially way in which a first stage generates information used by the succeeding stage.

BasePipeline

Description

BasePipeline is the simplest connector in charge of the sequential execution of the different stages composing the pipeline. These stages are executed in the specified order.

Path

auracog_pipelines.pipelines.base.BasePipeline

Configuration

No configuration is required

Docs:

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

Nabro normalization pipeline

Description and stages

Nabro is a pipeline used for the normalization of the user’s utterance through the execution of the following normalizers:

PunctuationNormalizer
SplitPunctNormalizer
SpaceNormalizer
CurrencyNormalizer
UnicodeNormalizer
LowercaseNormalizer

Configuration

This stage requires the following configuration in the nlp.json configuration file:

For the specific language and channel, in the nlp field of this JSON file, the key normalizer_pipeline_class must be filled in with the value: auracog_pipelines.pipelines.normalization.nabro.NabroPipeline

{
  "es-es": {
    "mp": {
         "nlp": {
         "normalizer_pipeline_class": "auracog_pipelines.pipelines.normalization.nabro.NabroPipeline"
      }
    }
  }
}

Docs:

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

Catalog of NLP stages

NLP stages to compose the NLP pipeline

Aura Platform Team has implemented a set of natural language processing (NLP) stages in order to configure different pipelines.

Select your intended stage in the left menu. Each of them is characterized by its description, path, files and configuration.

Section	Content	Role in the NLP process
Description	Identification and objective of the stage in the recognition process	Descriptive purpose of the stage in the recognition process
Path	Class path (Python class) of an element (stage or connector)	The path of each stage of the pipeline must be included in the file `pipeline.json` for building up the NLP dynamic pipeline
File	Specific training files and test set files for the NLP stage required to train and validate the NLP model	Linguists must generate these files for the training and the validation of the NLP model during the data resources definition
Configuration	Required configuration for each NLP stage	Configuration of each stage of the NLP model

Docs:

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

Prerequisites for working with Aura NLP

Key requirements that are essential to configure the Aura NLP development environment, prior to the generation and training of an understanding model

Introduction

Before starting the development of use cases over Aura NLP, there are certain tasks that must be carried out in order to install and configure this component:

Get sure your Aura system includes the mandatory technical resources for working with Aura NLP.
Install the Aura NLP Virtual Machine.
Generate a local branch for the Aura NLP data repository.

Docs:

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

Abacus 1.0.0. initial set-up

Using Abacus for the first time? Follow these guidelines for its set-up.

⚠️ This process must be done only once, the firt time you open Abacus.

Prerequisites for using Abacus

Check that you fulfil these requisites before Abacus set-up.

You have the NLP Virtual Machine installed and working, with your aura-nlpdata working branch generated.
The understanding model is already defined and configured.
You have generated the specific training files and E2E test files required for each stage of your NLP pipeline.
You have already filled the variables required for training in the configuration file build_local_variables.sh.

Steps for Abacus set-up

Access the NLP Virtual Machine.
Enter your local working project, henceforth {Root_project}, whose name should be:
aura-nlpdata-[country-code]
Copy the local variables configuration template: "${Root_project}/tools/build_local_variables.sh.tpl"
and rename as:
"${Root_project}/tools/build_local_variables.sh"
```
cd ${Root_project}/tools
cp build_local_variables.sh.tpl build_local_variables.sh 
```

Access the file build_local_variables.sh in the tools/ folder.
Fill in the variables inside the “run_web_trainings” section:
- TRAINING_WEB_AZURE_BASE_URL and TRAINING_WEB_AZURE_SAS_TOKEN variables:
  Ask the APE Team for them.
- GITHUB_TOKEN variable:
  - Generate a GitHub token:
    - Enter GitHub with your profile
    - Verify your email address if you haven’t done it yet
    - Go to GitHub token settings and generate a new token
    - Fill in the name and expiration date of the token
    - Select the scopes (Recommended: activate repo)
    - Click Generate token
  - Copy the token in the variable GITHUB_TOKEN.
    ⚠️ Make sure you copy it, as it will only shown once.

Run the script file:

${Root_project}/tools/run_web_trainings.sh

When the script is finished, Abacus is opened automatically.

Docs:

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

Technical resources for working with Aura NLP

Mandatory resources required by NLP experts of linguists in order to work with Aura NLP

Resources list

🔹 Aura NLP technical resources 🔹
Aura installation - Latest Aura Platform release
Operating systems - Linux over distribution Ubuntu 18.04 LTS (with Java preinstalled)
Configuration of development environment - Python 3.9. - Pip3 - virtualenv - For Linux distributions: libsqlite3-dev liblzma-dev libbz2-dev
Software - GitHub licence - Text editor: Pycharm or similar - Use of Grammars: Unitex/Gramlab open-source corpus processing suite - Grammars engine: GrapeNLP - CLU stage: Microsoft CLU account - OpenAI stage: Azure OpenAI Service account
NLP Training and testing tool Abacus 1.0.0.

Docs:

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

Aura NLP Virtual Machine user guide

Guidelines for the installation of Aura NLP Virtual Machine, required for the configuration of the NLP development environment

Installation and operation guidelines

Aura Platform Team has generated a Virtual Machine that allows the configuration of the Aura NLP development environment following a semi-automatic process.

Follow the steps explained below to install and operate it:

Install VirtualBox (or other software).
Import OVA formatted files that contain all the technical requirements for the installation.
Once the VirtualBox is installed, follow these steps:

3.1. Select “File” -> “Import Appliance”

3.2. Access Aura NLP Virtual Machine for your release in the Sharepoint L-CDO repository and select the corresponding aura-nlpdata.ova file for importing it.

3.3. Click on “Next >” button and, afterwards, select the “Import” button.

3.4. When the importation process has finished, in the main view of VirtualBox the new Virtual Machine is shown. Click over the new virtual machine and then press “Start”.
Ask the APE Team for the user and password to access.
Generate a new SSH key to operate the Virtual Machine
In order to operate with the NLP Virtual Machine, it is required to generate a new SSH (Secure Shell Protocol) key. For this purpose, follow the steps described in the section Generate a new SSH key and add it to the ssh-agent.

Be aware of the time update, as if the Virtual Machine is paused, the time is not updated and it can lead to errors with certificates.

Generate a new SSH key and add it to the ssh-agent

In order to operate with the NLP Virtual Machine, certain configuration is needed to allow users to access GitHub NLP repositories.

You can access and write data in repositories on GitHub using SSH (Secure Shell Protocol). When you connect via SSH, you authenticate using a private key file on your local virtual machine.

SSH configuration guidelines

Follow the steps explained below to configure the SSH keys:

Open VirtualBox and run the NLP Virtual Machine by clicking in the “Start” button.
After login into the VM (if you do not remember the password, ask APE team), open the terminal.
In the terminal, type in the command: ssh-keygen -t ed25519 -b 4096 -C your-email@telefonica.com, replacing your-email by your corporate e-mail. This command generates a new pair of SSH keys using the ed25519 algorithm. After introducing the command, press “enter” as shown in the following image.
Now that we have our SSH key pair generated, introduce the following command: ssh-add ~/.ssh/id_ed25519. This command adds the private key id_ed25519 to the SSH agent, allowing SSH connections to use that key without requiring the password each time we need to access the repositories.
The next step is to display the content of the id_ed25519.pub file, which contains the public SSH key. To do this, type in the following command: cat ~/.ssh/id_ed25519.pub. We need to copy the displayed key to add it to GitHub in the following steps. Copy everything except your email address, displayed at the end of the string.
Open GitHub in a web browser and log in.
In the top-right corner, click on your profile image, and select “Settings”.
In the new page, on the left-hand side bar, click on “SSH and GPG keys”, and then click on “New SSH key” button (in the top right corner).
Now, add a title for the SSH key, for example, “VM NLP”. The key type should be Authentication Key, and in the key field, add the key copied from the terminal in step 5. Finally, click on “Add SSH key” button.
In the list of SSH keys shown after clicking “Add SSH Key” in the previous step, identify the recently created SSH key and, on the right-hand side, click on the “authorize” button, as shown in the following image. GitHub will prompt you to verify with your password in order to authorize the Telefónica organization.
Now that we have our SSH keys set up, we can proceed with cloning the repositories we need to work with. Remember that to clone the repositories from the VM, we must click on “SSH” to clone via SSH and copy the URL.

Docs:

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

aura-bot-kpis utility

aura-bot-kpis utility allows managing KPI entities in aura-bot and aura-groot.

Introduction

The aura-bot-kpis utility contains the necessary utilities to manage KPI entities in aura-bot and aura-groot.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/src/aura-bot-kpis/

These guidelines will allow you to get a copy of the project running on your local machine for development and testing purposes.

Run tests

This project uses Jest for BBDD testing.

Unit tests

$ npm run test

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Coverage tests

You can run the coverage tests using:

$ npm run test

The threshold established to validate the coverage is as follows:

lines: 90%
functions: 90%
statements: 90%
branches: 70%

Versioning

We use [SemVer] (http://semver.org/) for versioning.

More information regarding latest versions:

$ npm show @telefonica/aura-bot-kpis

Docs:

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

aura-bot-library-util utility

aura-bot-library-util utility contains different utility files for aura-bot libraries

Introduction

aura-bot-library-util utility is an NPM library with utility functions provided by the Aura Bot Global Team to make it easier the development of dialogs in aura-bot.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/src/aura-bot-library-util/

This library only contains utilities used in the dialogs, not needed by the bot itself.

To use it, just define the dependency with @telefonica/aura-bot-library-util in your package.json file. It is published as a private library in NPM, so request a valid NPM token to access it.

The utility files included in aura-bot-library-util utility are described in the following sections.

CurrencyUtils

aura-bot-library-util/currency-util.ts

getLocalizedCurrency

It returns money amounts formatted with country specific settings.

param	type	description	mandatory
locale	string	Country locale code	yes
amount	number	Total amount to be formatted	yes
currency	string	Country currency code	yes


    const amount: string = getLocalizedCurrency('es-es', 460.56, 'EUR');

    /* 460.56 € */

    const amount: string = getLocalizedCurrency('es-uy', 460.56, 'UYU');

    /* $ 461 */

Datautils

aura-bot-library-util/data-unit-util.ts

getDataAndUnit

It returns converted internet data amount and unit from bytes quantity, following the country specific settings.

param	type	description	mandatory
content	TurnContext	Step context	yes
configuration	Configuration	Dialog config variables	yes
data	number	Data amount	yes
forcePoint	boolean	It indicates if the decimals will be separated by points	no


    const [dataQt, dataUnit] = getDataAndUnit(context, config, 1536)
    const [dataQt, dataUnit] = getDataAndUnit(context, config, 1536, true)

    /*
     * Result depending on AURA_DEFAULT_LOCALE env var
     * pt-br - ['1,5', 'GB']
     * en-gb - ['1.50', 'GB']
    */

LocaleUtils

aura-bot-library-util/locale-util.ts

getLiteral

This intermediate method generates a getText function ready to receive resources keys and sequential params.

param	type	description	mandatory
context	TurnContext	step context	yes
library	string	libraryName	no


    /* If we need to convert only one text in function scope, we can use it as one line function */

    const text: string = getLiteral(context, 'services')('services.find.moreinfo', param1, param2);
    const text: string = getLiteral(context)('services:services.find.moreinfo', param1, param2);

    /* When we need to convert several texts in function scope for the same library,
    we can preassign result function to variable and proceed all along dialog step */

    const getServicesText: Function = getLiteral(context, 'services');

    const text: string = getServicesText('services.find.moreinfo', param1, param2);

    /* if we need to convert several texts in function scope for several libraries */

    const getText: Function = getLiteral(context);

    const text: string = getText('services:services.find.moreinfo', param1, param2);
    const errorText: string = getText('errors:error.notFound');

getTextByKeys

Factory function used mainly in graphs to retrieve converted text objects, avoiding redundancy.

param	type	description	mandatory
context	TurnContext	step context	yes
libraryName	string	libraryName	yes


    const getGraphText: Function = getTextByKeys(context, 'graphics');

    const texts: any = getGraphTexts(['of', 'remaining'], { unit: 'data.gb' })

    /* Output
        {
            of: 'graphics:of', // converted text,
            remaining: 'graphics:remaining', // converted text,
            unit: graphics:data.gb, // converted text
        }
    */

withLocale

It encapsulates all data we need to call LocaleManager instance getText method.

param	type	description	mandatory
context	TurnContext	step context	yes
fn	Function	function to be executed at the end	yes
library	string	libraryName	no

For instance, getLiteral function passes an inline arrow function to simply receive the params that the result function was invoked with:


    /**
     * handy method to retrieve text.
     *
     * @param  {TurnContext} context The dialog step context.
     * @param  {string} libraryName? Library name.
     */
    export function getLiteral(context: TurnContext, libraryName?: string) {
        return withLocale(
            context,
            ({ getText, library }: any, literal: string, ...args: any[]) => getText(`${library ? library + ':' : ''}${literal}`, args),
            libraryName
        );
    }

This way, we can compose any method that fits our dialog text composition specific needs. A trivial working code sample could be:


    const _getText: Function = withLocale(stepContext.context, intermediateFunc)

    function intermediateFunc({ getText }, obj: any, params: string[], isError?: boolean) {
        const finalTextKey: string = isError ? obj.error : obj.text;
        return getText(finalTextKey, params);
    }

    const obj = {
        text: 'services:services.some.text',
        error: 'errors:error.message.error'
    }

    const text: string = _getText(obj, ['first', 'second']);
    const errorText: string = _getText(obj, [], true);

getErrorMessage

It composes a full error message with fallback text when required.

param	type	description	mandatory
context	TurnContext	step context	yes
statusCode	number	request code, if existing	nullable
objErr	StatusCodeMessagesMap	Custom error messages	no

    export interface StatusCodeMessagesMap {
        default: string;
        code400?: string;
        code404?: string;
    }
    try {
        //Do stuff
    } catch (error) {
        const messageMap: StatusCodeMessageMap = {
            default: 'services:services.custom.error',
            code400: 'services:services.error.badRequest',
            code404: 'services:services.error.notFound'
        }

        const errorMessage: string = getErrorMessage(stepContext.context, error.code, messageMap)
    }

sendLoggerErrorAndActivity

It sends full logged error message activity.

param	type	description	mandatory
context	TurnContext	step context	yes
logger	any	log function	yes
objErr	StatusCodeMessagesMap	Custom error messages	yes
dialogId	string	Current dialog ID	yes
error	any	error to print	yes

    try {
        /* [...] */
    }  catch (error ) {

        const messageMap: StatusCodeMessageMap = {
            default: 'services:services.custom.error',
            code400: 'services:services.error.badRequest',
            code404: 'services:services.error.notFound'
        }


        sendLoggerErrorAndActivity(
            context,
            this.logger,
            messageMap,
            ServicesFindDialog.id,
            error
        )
    }

LibraryUtil

aura-bot-library-util/library-util.ts

excludeDialogs

It excludes dialogs provided in an array.

param	type	description	mandatory
dialogNames	string[]	Array with dialog’s ids	yes
options	any	Options to customize function behavior	yes

excludeDialogs(dialogNames: string[], options: any);

readLocaleFolder

Ir returns an object with locale name as key and file content as value.

param	type	description	mandatory
localePath	string	`localePath` Base path where locale files are looked for	yes

readLocaleFolder(localePath: string);

readEnv

It returns an object with env variables from current environment.

param	type	description	mandatory
configuration	any	Object with configuration information	yes
envPath	string	Path pointing to environment configuration	yes

readEnv(configuration: any, envPath: string);

readDialogConfig

It returns an object with dialog config from current environment.

param	type	description	mandatory
configuration	any	Object with configuration information	yes
configPath	string	Path pointing to dialog configuration	yes

readDialogConfig(configuration: any, configPath: string);

replaceToDialogByIntent

Given an intent, it replaces the current dialog by the intent that matches with it. This method triggers the main dialog and keeps the context-filter functionality in the replaced one.

param	type	description	mandatory
stepContext	WaterfallStepContext	step context	yes
intent	string	intent which the dialog will be triggered	yes

await replaceToDialogByIntent(stepContext: WaterfallStepContext, intent: string);

generateSasUrl

It generates and returns the URL of the blob resource, applying expiration.

param	type	description	mandatory
fileName	string	Blob file name	yes
remoteContainerPath	string	Full container’s path	yes
expiration	number	Expiration time in minutes	no
configuration	Configuration	Environment configuration	yes
correlator	string	Correlator	no

await generateSasUrl(fileName: string, remoteContainerPath: string,
    configuration: Configuration, corr?: string, expiration?: number);

uploadFileUrl

It uploads a file to Azure Storage from an URL.

param	type	description	mandatory
sourceUrlFile	string	URL that contains the file	yes
remoteFilePath	string	Blob remote path	yes
configuration	Configuration	Environment configuration	yes
correlator	string	Correlator	no
containerName	string	Storage container name	no

await uploadFileUrl(sourceUrlFile: string, remoteFilePath: string,
    configuration: Configuration, corr?: string, containerName?: string) ;

ResourcesUtils

aura-bot-library-util/resources-util.ts

getImageUrl

It intercalates supported resolution folder path into image path, following channel image resolution settings.

param	type	description	mandatory
context	TurnContext	step context	yes
libraryName	string	Library proper name	yes
url	string	Full path of the image default version in the library root folder	yes
configuration	Configuration	Env variables	yes

    // Current supported resolutions.
    enum SupportedResolutions {
        HDPI = 'hdpi',
        XHDPI = 'xhdpi',
        XXHDPI = 'xxhdpi',
        XXXHDPI = 'xxxhdpi'
    }

    // Taking channelData imageSettings resolution == xxxhdpi

    getImageUrl(context, 'services', 'images/default/imageName.png', configuration);

    // https://<storageUrl>/libraries/services/images/xxxhdpi/imageName.png?<params>

getResourcePath

It gets the whole resource path uploaded to blob-storage, that is accessible, to be included in cards.

param	type	description	mandatory
configuration	any	Env variables	yes
libraryName	string	Library proper name	yes
baseFilePath	string	Base file access path	yes

const uri: string = DialogUtils.getResourcePath('generic', resource, this.configuration);

Docs:

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

aura-channel-data-handler utility

aura-channel-data-handler utility allows managing channelData content

Introduction

The aura-channel-data-handler utility contains the necessary utilities to manage the content of []channelData](/docs/components/request-response-model/) for the input/output response to aura-bot.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-utilities/src/aura-channel-data-handler/

These guidelines will allow you to get a copy of the project running on your local machine for development and testing purposes.

Run tests

This project uses Mocha for BBDD testing.

Unit tests

$ npm run test

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Coverage tests

You can run the coverage tests using:

$ npm run test

The threshold established to validate the coverage is as follows:

lines: 90%
functions: 90%
statements: 90%
branches: 70%

Use aura-channel-data-handler utility

Transform channelData from an old version to the latest version (normalized)

The mapper will try to obtain the correct mapper based on the version indicated in version field. If the request does not contain a version, it will try to map using version 1.0.0:

import { ChannelData, ChannelDataRequestMapper } from '@telefonica/telefonica/aura-channel-data-handler';
...
const channelData: ChannelData = ChannelDataRequestMapper.getNormalized(context.activity.channelData);

Continuing with the previous example, the channelData obtained from the normalization can also be used as a helper to perform predefined operations:

// You can get the original request (example v1)
...
import { ChannelDataRequestHelper } from '@telefonica/telefonica/aura-channel-data-handler';
...

const helper: ChannelDataRequestHelper = channelData as unknown as ChannelDataRequestHelper;
const channelDataOriginal = helper.getOriginalRequest();

Versioning

We use [SemVer] (http://semver.org/) for versioning.

More information regarding latest versions:

$ npm show @telefonica/aura-channel-data-handler

Docs:

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

aura-minibot-service utility

aura-minibot-service simplifies how aura-mini-bot and aura-mini-groot are generated.

Introduction

The aura-minibot-service utility contains the common elements needed by aura-bot and aura-groot to generate their mini versions: scripts, mock classes and templates, etc.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/src/aura-mini-bot-service/

These guidelines will allow you to get a copy of the project running on your local machine for development and testing purposes.

Run tests

This project uses Jest for BBDD testing.

Unit tests

$ npm run test

Style tests

These tests perform the validation coding rules defined in Aura using the eslint tool.

You can validate the code using:

$ npm run lint

Coverage tests

You can run the coverage tests using:

$ npm run test

The threshold established to validate the coverage is as follows:

lines: 90%
functions: 90%
statements: 90%
branches: 70%

Versioning

We use [SemVer] (http://semver.org/) for versioning.

More information regarding latest versions:

$ npm show @telefonica/aura-minibot-service

Docs:

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

aura-movistar-libraries utility

aura-movistar-libraries utility contains utilities to use with dialogs in Movistar channels

Introduction

aura-movistar-libraries utility is an NPM library that contains utility functions provided by Aura Global Team to be used with dialogs in Movistar channels:

Movistar Home
Movistar Plus
Set-top-box (STB)

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/src/aura-movistar-libraries-utilities/

To use it, just define the dependency with @telefonica/aura-movistar-libraries-utilities in your package.json. It is published as a private library in npm, so request a valid NPM token to access it.

models/intent-models

It contains all the necessary classes and interfaces for Movistar use cases. Some of these classes and interfaces are: MovistarPlusResolution, MovistarStatus, SuggestionAction, etc.

utils/movistar-payload-utils

It contains the functions executed to fill the payload of the message depending on the settings/payloadType in the intent configuration.

The principal functions are: getPayloadDefault, getPayloadCommunications, getPayloadTV and getPayloadWifi.

utils/movistar-resolution-utils

It contains the function to make a query to the Movistar plus resolution API. This query returns a MovistarPlusResolution object that contains suggestions, actions, sound, payload, etc.

Object example returned by getMovistarPlusResolution with intent intent.common.greetings in the STB channel:

{
      "intent":"intent.common.greetings",
      "entities":[

      ],
      "resources":[
         {
            "type":"title",
            "name":"tv.notUnderstand",
            "params":{

            }
         }
      ],
      "status":"ok",
      "payload":{
         "type":"",
         "data":{

         },
         "data_additional":{

         },
         "action":"NONE",
         "status":{
            "code":"470",
            "message":"Intent not Supported Error - General Code",
            "info":{ 

            }
         }
      },
      "user_action":{

      },
      "suggestions":[
         {
            "intent":"intent.tv.display",
            "entities":[
               {
                  "entity":"Canal Cocina",
                  "type":"ent.audiovisual_channel",
                  "score":1,
                  "canon":"Canal Cocina",
                  "label":""
               }
            ],
            "resources":[
               {
                  "type":"title",
                  "name":"tv.switchToChannel.suggestion.title",
                  "params":{
                     "channels":"Canal Cocina"
                  }
               },
               {
                  "type":"button",
                  "name":"tv.switchToChannel.suggestion.button",
                  "params":{
                     "channels":"Canal Cocina"
                  }
               }
            ]
         }
        /// More suggestions were returned but are ommited in this example object
      ],
      "sound":"none"
   }

utils/movistar-utils

A compendium of utilities which formats activity’s channelData to be compatible with Movistar channels.

The principal function of this file is getMovistarMessage. It returns a properly formed channelData message for the Movistar channels, depending on the input parameters and the settings field in the configuration of the intent. All other functions are auxiliary of this principal.

Example of object returned by getMovistarMessage with input params:

Input params

Context: Context of the dialog
Text: null
MovistarConfig:

{
   "type":"common",
   "action":"COMMON.GREETINGS",
   "locales":{
      "success":[
         "common:common.greetings.main"
      ],
      "error":[
         "common:common.error.main"
      ]
   },
   "needTvResolution":true
}

MovistarPlusResolution: Same as show in previous example

Output message

{
   "text":"Hola, buenas",
   "channelData":{
      "intent":{
         "id":"intent.common.greetings",
         "name":"intent.common.greetings",
         "entities":[

         ]
      },
      "content":{
         "text":"Hola, buenas",
         "speak":"Hola, buenas",
         "sound":"positive",
         "actions":[

         ]
      },
      "dialogContext":[
         {
            "text":"Quiero ver Canal Cocina",
            "value":{
               "intent":"intent.tv.display",
               "entities":[
                  {
                     "entity":"Canal Cocina",
                     "type":"ent.audiovisual_channel",
                     "score":1,
                     "canon":"Canal Cocina",
                     "label":""
                  }
               ]
            }
         }
         /// More suggestions were returned but are ommited in this example object
      ],
      "customData":{
         "type":"common",
         "action":"COMMON.GREETINGS",
         "data":{

         },
         "data_additional":{

         },
         "status":{
            "code":"200",
            "message":"Success - General Code",
            "info":{

            }
         }
      },
      "fullScreen":false,
      "version":"1.0.0"
   },
   "inputHint":"acceptingInput",
   "attachments":[
      {
         "contentType":"application/vnd.microsoft.card.hero",
         "content":{
            "buttons":[
               {
                  "type":"postBack",
                  "title":"Quiero ver Canal Cocina",
                  "value":{
                     "name":"Quiero ver Canal Cocina",
                     "text":"Ver Canal Cocina",
                     "type":"suggestion",
                     "intent":"intent.tv.display",
                     "entities":[
                        {
                           "entity":"Canal Cocina",
                           "type":"ent.audiovisual_channel",
                           "score":1,
                           "canon":"Canal Cocina",
                           "label":""
                        }
                     ],
                     "inputIntent":"intent.common.greetings",
                     "inputEntities":[

                     ]
                  }
               }
               /// More suggestions were returned but are ommited in this example object
            ]
         },
         "name":"SUGGESTIONS"
      }
   ]
}

suggestionType

Formerly, there was a differentiation between channels based on their prefix. This implementation was quite strict and to parameterize this behavior a new configuration variable has been developed.

SuggestionType must be configured for channels Movistar-Plus, Set-on-Box and Set-on-Box-Haac and its value can be either actions or attachments describing where suggestions must be placed in activity’s channelData.

‘actions’: Movistar-Plus
‘attachment’: Set-on-Box, Set-on-Box-Haac

Docs:

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

aura-server-common utility

aura-server-common utility allows code sharing between Aura server applications

Introduction

The aura-server-common utility is a library for sharing code between Aura server applications.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-utilities/src/aura-server-common/

For this component, SemVer is used for versioning.

Tests running

This project uses tslint to validate the coding style.

Unit tests

To execute the tests, use the following command:

$ npm run test

Coding style tests

These tests perform the validation coding rules defined in Aura using the tslint tool.

You can validate the code using:

$ npm run lint

Developer notes

The folder structure used for development is:

.
├── __test__            // Folder for test in jest
└── src                 // Shared code between APIs and modules.
    ├── handlers        // Expressjs handlers folder
    ├── middlewares     // Expressjs middlewares folder
    ├── models          // Models
    ├── modules         // Modules to be loaded by orchestrator
    ├── routes          // Expressjs routes folder
    └── utils           // Common utilities

Handlers

validate-auth-apiKey: To get or create the correlator and validate the APIKey of the request.
validate-google-auth: To validate the Google x-goog-signature of the request.

Middlewares

error-handler: Global error handler.
incoming-request: To register metrics for incoming requests.
set-correlator: To get the correlator from several places.
set-not-cache: To set Cache-Control and ETag headers to prevent caching.
validate-apiKey: To get or create the correlator and validate the APIKey of the request.
validate-token: To validate the token.

Modules

async-hooks-blocking: To manage async hooks and capture stack traces.
configuration-manager: To manage config and load environment variables.
oas-manager: To register security handlers, for example openAPIBackend.
plugin-manager: To manage plugins to add different services.
prometheus-manager: To manage Prometheus metrics.

Routes

generic: To manage generic routes such us: healthz, favicon and shutdown.
metrics: To manage metrics routes.

Utils

aura-error-factory: Collection of functions to manage conversion errors.
oas-utils: Collection of functions to manage token, validation failures and error responses.
time-utils: Collection of functions to manage time.
token-validations: Collection of functions to validate tokens.

Plugins

dapr-pubsub-service: plugin which allows the interaction with the Dapr PubSub Service

Docs:

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

Guidelines for building an Aura Bot library

Orderly steps for building a library in Aura Bot when developing a use case

Introduction

The customization of aura-bot is done through libraries: libraries in aura-bot are node.js packages, with a particular structure of folders and files that contain one or several dialogs, plus i18n strings, environment variables, configuration files and graphical resources. Libraries are deployed in the bot as plugins.

Within these libraries’ structure, developers are able to build extensions over aura-bot global components (dialogs) to be deployed in concrete scenarios where customized capabilities and functionalities are required, such as the development of a new use case.

The following sections include the detailed steps for building or modifying a library over aura-bot.

Build an Aura Bot library

When developing a local use case in Aura, you should:

✅ For local use cases generated from scratch: develop a new use case library
✅ For local use cases based on the customization of a global use case: modify existing use case library

We can have one or several libraries in one repository:

If the repository only contains one library, the root/ folder can be used. In this case, the folders of the library can be created directly from the root/ folder.
For example, for the src/ folder: [repository_name]/src
If the repository contains more than one library, a folder hierarchy is required. The working directory is:
For example, for the src/ folder: [repository_name]/[library name]/src

# Optional, only with multiple libraries in same repository (replace newlibrary with library name)
$ mkdir -p packages/newlibrary
$ cd packages/newlibrary
# Creates the src folder and move the dialog files inside
$ mkdir src

⚠️ The names of Aura global libraries are reserved. Therefore, both for the creation of a new local library or a customization of a global one, constructors must use a different name in order to avoid overlapping. We recommend to use the following structure for local libraries’ names: [local_library_name]-[OB]

⚠️ The library name must be exactly the same in all its associated files.

At this stage, you should build the structure of your library repository, with all the required folders and files.

📌Practical tip
Use a global library as template, copy it and edit the corresponding folders and files for your use case.
You can use: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill. This library will be used as an example throughout the document.

The recommended order is detailed below:

Copy in the root of the library the generic required files as identical copies: .gitignore, .npmignore, tsconfig.json and tslint.json.
Create a package.json containing a plugin block with the name of the service this plugin will provide.
ℹ️ Detailed guidelines: Section package.json
A README.md file will be also desirable, explaining the library.
Create one file within src/ folder for each dialog (parts common to several dialogs could share utility clases, as usual).
ℹ️ Detailed guidelines: Use case dialogs Now, copy here your dialog or code the it as explained in General guidelines for building an Aura Bot dialog.
Create an index.ts file, that will register all the dialogs when loading the plugin.
ℹ️ Detailed guidelines: index.ts

After publishing or npm linking the package (or npm packing), this plugin could be loaded from aura-bot by declaring the package name in the plugin configuration array. Additionally, any of the dialogs could be excluded from the load. A simple plugin configuration file could be:

[
    "@telefonica/aura-bot-bill-library",
    "@telefonica/aura-bot-common-library",
    {
        "packagePath": "@telefonica/aura-bot-other-library",
        "exclude": [
            "./first-dialog"
        ]
    }
]

Note that the object format (with packagePath) is optional. When no options are passed to the plugin, we could just use a string with the name of the package. When there are more options (like exclude array), the object format must be used. So, these two configuration files are equivalent:

[
    "@telefonica/aura-bot-bill-library",
    "@telefonica/aura-bot-common-library"
]

and

[
    {
        "packagePath": "@telefonica/aura-bot-bill-library"
    },
    {
        "packagePath": "@telefonica/aura-bot-common-library"
    }
]

Aura bot libraries repository

A library in aura-bot must contain a fixed structure of folders and files, both mandatory or optional.

These elements can differ for different environments, deploys or channels.

Folder / Files	Content
src/	- `<dialog-name>.ts` files: Files containing the dialogs logic - `index.ts` file: Registration of dialogs in the library. Declaration of locale, config and `.env` files of the library. - `configuration-schema.ts`: schema for library-specific configuration variables - Unit tests for each dialog: `<dialog-name>.spec.ts`
settings/	- `locale` folder: Definition of text resources for Aura response - `dialog-config.json`: Mapping of intents with dialogs within the library; definition of context filters - `.env` files: Definition of environment variables associated with the library
resources/	Optional folder including files for composing Aura response
package.json	File that contains a plugin block with the name of the service this plugin provides
package-lock.json	File including the versioning control Do not modify it
Other files	`.gitignore`, `.npmignore`, `tsconfig.json` and `tslint.json` Copy them in the root library as identical copies and do not modify them
Readme.md	Optional file with information regarding the library

src/ folder

Working directory: [repository_name]/src/ or [repository_name]/[library name]/src/
This folder must contain three different types of files:

src/ content	Mandatory/Optional
File(s) containing the use case dialog(s): `<dialog-name>.ts`	Mandatory
`index.ts` file	Mandatory
`configuration-schema.ts`	Optional

📌Practical tip Check the src/ folder in our global library: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill/src

Use case dialogs

Dialogs are .ts files containing the dialog logic. Bot developers must generate the associated dialog(s) for their use case following the guidelines defined in General guidelines for building an Aura Bot dialog.

Afterwards, remember that all the developed dialogs must be tested.

index.ts file

index.ts file registers all the dialogs in the library.

Once the use case dialog is developed, edit this file with the corresponding values for each field explained below:

let dialogNames: names of all the dialogs included in the library.
register:
- <libraryName>: library name.
- dialogs: it points to the dialogs declared in let dialogNames.
- locale: the locale files must be exposed in the locale property when registering the plugin in order to be merged (during the make-up process).
- env: the .env files must be exposed in the env property when registering the plugin in order to be merged (during the make-up process).
- config: the config files must be exposed in the config property when registering the plugin in order to be merged (during the make-up process).
- configSchema: declaration of specific variables for the use case included in the configuration-schema.ts file.
- resources: it indicates the path (__dirname) where the resources folder, containing the resources used in the use case, is included: resources: path.resolve(__dirname, '..', 'resources')

A complete example can be found below for the library generic:

  import * as path from 'path';
import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
import configurationSchema from './configuration-schema';


export = function setup(options: any, imports: any, register: (err: Error, result: any) => void) {
    let dialogNames = [
        './generic-dialog'
    ];
    // If there is an array of dialogs to disable, remove from dialog array
    libraryUtil.excludeDialogs(dialogNames, options);
    // Register that this plugin has been fully loaded
    const settingsPath = path.resolve(__dirname, '..', 'settings');
    register(null, { resources: path.resolve(__dirname, '..', 'resources')
        generic: {
            dialogs: dialogNames.map(dialogName => require(dialogName)),
            locale: libraryUtil.readLocaleFolder(path.resolve(settingsPath, 'locale')),
            env: libraryUtil.readEnv(settingsPath),
            config: libraryUtil.readDialogConfig(settingsPath),
            configSchema: configurationSchema,
            resources: path.resolve(__dirname, '..', 'resources')
        }
    });
};

configuration-schema.ts

Optional file for the validation of schemas from the library-specific configuration variables required for the use case. When the bot loads all the plugins, it verifies that the schemas provided by the library fulfil the conditions established in the current file.

The orderly process for editing this file is defined below:

Declare the library-specific configuration variables in the .env configuration file starting with the library name: [library_name]_[variable_name]. This file includes the values of these variables.
For these variables, include in the configuration-schema.ts restrictions, default values, checking, etc. in order to validate them. During the during the make-up process, the content of the different configuration-schema.ts files for each library will be automatically uploaded into a .env.libraries file.

You can create a schema (using @hapi/joi) and specify the name of the library-specific variable as shown in the following example:

import joi from 'joi';

const configurationSchema = {
    LIBRARYNAME_DEFAULT_GREETINGS: joi.string().default('hello'),
    LIBRARYNAME_COMMON_COUNT_GREETINGS: joi.number().default(1800)
};

export default configurationSchema;

settings/ folder

Working directory: [repository_name]/src/ or [repository_name]/[library name]/src/
This folder must contain three different types of files:

settings/ content	Mandatory/Optional
`locale`folder	Optional
`dialog-config.json` file	Mandatory
`.env`configuration files	Optional

📌Practical tip Check the settings/ folder in our global library: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill/settings

locale/ folder

Each library may contain (optionally) a settings/locale folder, with one or more locale files with the format: settings/locale/dialog-config.<culture_code>.json

The content of this file corresponds to the text resources, both from aura-bot core or text of Aura response for a specific use case. This content can be generated using POEditor, which handles the different messages that the bot shows to the customer and to adapt them to a specific language.

Find detailed information for the generation of texts included in Aura response in Build Aura response: POEditor texts.

⚠️ These files must be generated during the building up of a dialog, as they must be included in the unit tests for the dialogs.

An example of this file is shown below:

[
  "common:common.goodbyes.main": [
        "See you soon.",
        "See you soon."
    ],
    "common:common.greetings.main": [
        "Hello. How can I help?"
    ],
    "common:common.thankyous.main": [
        "Happy to help",
        "Happy to help."
    ]
}

dialog-config.json

dialog-config.json is a mandatory file that maps each intent with a dialog from the library. Therefore, the dialog is launched if the intent is recognized. Moreover, the file defines the suitability of the use case and allows the definition of context filters.

Each library must contain a dialog-config.json file that can be general or defined per language and OB. This general configuration could be merged (with higher priority) with a specific file per language and OB: dialog-config.<AURA_DEFAULT_LOCALE>.json where AURA_DEFAULT_LOCALE contains the culture code to be used by default in the current deployment: en-gb, es-es, etc.

The dialog-config.json file follows the DialogLibrary model, excepting for the field onlyIn which is described below.

onlyIn property

The OnlyIn field is an optional field that indicates to which channels the dialog will be added. If it is not present, it means that the dialog will be added to all the channels of the environment. Configure it, if required, including an array of channels names.

contextFilters

A contextFilter allows to configure the behavior of a dialog depending on the fulfilment of specific conditions. You can define contextFilters in the dialog-config.json file for a specific intent.

Currently, the conditions that can be established correspond to the user’s subscription type (for example, prepaid or postpaid) and the type of contract (monomsisdn or multimsisdn). Depending on the fulfilment of the established condition (true or false), the behavior of the dialog is different.

For including contextFilters, edit the fields included in the ContextFilter model.

An example is shown below with authorization at library level, only a dialog, without contextFilters, that is returned without suggestions and that applies to all channels.

  {
 "name": "handover",
  "authorization": {
    "purposes": "customer-self-service",
    "scopes": "subscribed-products-user-read"
  },
  "dialogs": [
    {
      "id": "handover",
      "suggestions": false,
      "triggerConditions": [
        {
          "intent": "intent.common.handover"
        }
      ]
    }
  ]
}

The following example includes authorization at library level, only a dialog, without contextFilters, that is returned without suggestions and that applies only to Novum and Movistar Home.

 {
 "name": "handover",
  "authorization": {
    "purposes": "customer-self-service",
    "scopes": "subscribed-products-user-read"
  },
  "dialogs": [
    {
      "id": "handover",
      "suggestions": false,
      "triggerConditions": [
        {
          "intent": "intent.common.handover"
        }
      ],
     "onlyIn": ["novum-mytelco"]
    }
  ]
}

The third example includes contextFilters:

  "dialogs": [
             {
               "intent": "intent.billing.check",
               "contextFilters": [
                  {
                      "name": "subscrition_type_prepaid_invoice",
                      "type": "subscrition_type_filter",
                      "conditions": "/authData/subscriptionType eq 'prepaid'",
                      "true": {
                          "name": "subscription_type_prepaid_invoice_true",
                          "breakDialogExecution": true,
                          "breakFilterEval": false,
                          "resource": "bill:bill.check.prepaid",
                          "suggestions": true
                    }

NOTE: All intents of the same dialog must be defined together for each channel. Like:

  {
    "name": "mocks",
    "dialogs": [
        {
            "id": "mocksv3-dialog",
            "channelDataVersion": "v3",
            "triggerConditions": [
                {
                    "intent": "intent.tv.display"
                }
            ],
            "onlyIn": [
                "set-top-box"
            ]
        },
        {
            "id": "mocksv3-dialog",
            "channelDataVersion": "v3",
            "triggerConditions": [
                {
                    "intent": "intent.tv.search"
                },
                {
                    "intent": "intent.tv.display"
                }
            ],
            "onlyIn": [
                "movistar-plus"
            ]
        }
    ]
}

.env configuration files

When developing a use case, you must include in this file the values for the library-specific configuration variables required for the use case. These variables must be formatted as follows: [library_name]_[variable_name].

There can be multiple .env files corresponding to different libraries, environments, etc. All of them are automatically uploaded into a .env.libraries file during the make-up process.

A simple example of .env variables is shown below:

MYLIBRARY_VERSION=1.2.3
MYLIBRARY_ENDPOINT=https://my-library.test/v1

resources/ folder

The resource folder is optional and, if existing, is placed on the directory: [repository_name]/resources/ or [repository_name]/[library name]/resources/

It includes different folders with images or any other binary files (such as JSON files) required by the use case. Resources in this directory can be organized in different sub-folders: a default folder and locale folders for different culture codes.

📌Practical tip Check the resources/ folder in our global library: https://github.com/Telefonica/aura-bot-libraries/tree/master/packages/bill/resources

Declare in this folder the graphic resources of your use case, if existing. Inside each folder /images, if required, resources may be organized in sub-folders depending on the image resolution.

If existing, the files in the resources/ folder are uploaded to Azure container pointed by the AURA_STATIC_RESOURCE_ENDPOINT and the AURA_STATIC_RESOURCE_SAS_TOKEN environment variables, during the during the make-up process.

package.json file

The package.json is a mandatory file and is placed on the directory: [repository_name]/package.json or [repository_name]/[library name]/package.json

This file contains a plugin block, with the name of the service this plugin provides.

📌Practical tip Check the package.json file in our global library: https://github.com/Telefonica/aura-bot-libraries/blob/master/packages/bill/package.json

For including your use case, follow the structure shown below changing “newlibrary” with the name of your library:

"plugin": {
    "provides": [
        "newlibrary"
    ]
},

The package.json can contain different dependencies. Useful ones for libraries are:

@telefonica/aura-bot-utilities/lib/aura-bot-common: common library shared among aura-bot Platform and the corresponding library for global use cases.
@telefonica/aura-bot-utilities/lib/aura-bot-library-util: library with specific utilities for libraries, such as resource loading, currencies, etc.
@telefonica/aura-logging: recommended for Aura logs tracking.
botbuilder-dialogs: dialogs classes.

Docs:

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

Build an Aura Bot dialog

This section includes different processes for building an Aura bot dialog when developing a local use case, both general guidelines and specific ones for concrete scenarios

Introduction

Dialogs are software components that model conversations with the final users by interchanging messages with them. Currently, aura-bot supports the Microsoft Bot Framework SDK v4 for JavaScript as the internal bot engine.

When developing a local use case, that can be both an experience built from scratch or inspired in a global use case, the OB developers must build a new local dialog that includes the logic of the use case or modify an existing one.

The dialog will interact with the customer using a conversational interface, this is, interchanging messages back and forth and, if required, the dialog will summon Kernel or third-party APIs in order to fetch data to fulfil the user’s request.

Before getting started, we recommend you to read some useful Microsoft documentation:
📄 Send and receive text message
📄 Dialogs library

Scenarios for building a dialog

Bot developers can find different scenarios when building a dialog over aura-bot:

Build an Aura Bot library that will contain the dialog, in case it does not exist.
General guidelines for building a dialog: most common scenario for building a dialog over aura-bot
Build a dialog that use async APIs, that is, APIs that do not provide the information back immediately, but with a certain standby time as they must perform a specific task derived from the user’s request.
Configure bypass mode to force sending any input message to aura-bot directly to a external service and vice versa.
Build an operation, which are a type of intents that can be used inside a dialog’s conversational flow.
Migrate a dialog to channelData v3, including the steps for making your use case compatible with channelData v3.
Migrate use cases to Bot Framework 4.19, which is the version used by Aura’s upcoming architecture based on Microsoft skills protocol.

Docs:

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

How to write code in Aura Bot global repositories

Guidelines for developers willing to contribute to Aura Bot global repositories writing code

Introduction

The aim of this document is to establish common minimum rules to contribute in Aura Global repositories: code linting, used libraries and guidelines for working over main and master branches

Programming Languages

aura-bot code is written in typescript 4.3.4 that is a programming language developed by Microsoft on top of Nodejs. Currently we use node engine version 14 and npm version 6.

This means that we follow typescript rules of naming, but we have also added some extra ones, to unify our developments:

local variables: always in camelCase.
files: always in lower case letters, dash-separated.
classes: in PascalCase.
interfaces: in PascalCase, they do not start with I.
enums: named in PascalCase, each item also in PascalCase.
library or server names: always in lower case letters, dash-separated.
environment variables: in capital letters, underscore-separated.
functions: always in camelCase.
asynchronous programming: use await/async pattern when possible, avoid chains of promises.
adding a feature to an existing server: check the already existing instances of Singleton components and use them directly. Do not create a new instance, this will lead to an error during the start-up or in runtime.
All servers count on a ConfigurationManager where all its environment variables can be obtained.

Try to use the best programming pattern for each feature, applying always Single Responsibility Point defining small modules, functions or classes that do only one specific task. Find more references for programming patterns:

Libraries used

To write logs, always aura-logging. This logger needs a module name during its initialization: it must be in lower case letters, dash-separated.
- Review aura-utilities repository to find out more libraries.
Web servers: expressjs.
Dependency injection: architect.
Environment variables configuration validation: joi.
Database: mongodb, currently version 4.2 but moving in next releases to version 6.
UnitTest: we use mocha for already existing modules, but we are moving to jest, so all brand-new modules must use jest.
Mocks-Server: we have developed a mocks server (aura-mocks-server), that mimics the behavior of all external components (such as kernel, nlp, etc.). If something is missing, add it.
API definition:
- We use API FIRST design. i.e. firstly we define the swagger of the API and then we build the routing of the API using the swagger directly from expressjs and express-openapi.
- We use OpenApi v3 for swagger definition
- We generate the client of the API and the related models automatically after a change in the swagger file.
  - Client package is published on the fly to the correspondant npm registry (github during the development phase and npm for master and release), so its code never exists in the server repository.
  - Models package is updated in the server repository, but just using the definitions in the swagger, no extra code should be written.
- Swagger file must be called swagger.yml and must be created in the root of the server, at the same level of its package.json.
- Each server that needs a client must have a client folder with just the package.json of the client, the rest of the code is autogenerated by aura’s CI system.
HTTP requests: we use superagent library to handle HTTP request, both in our generated API clients and in those done directly from the servers. Currently we use version 5.2.2, but we are moving to version 8 in following releases.
- request and request-promise are strongly prohibited.

Work on a main branch

When you work on a main branch, the libraries are published on Github.

To install the dependencies of a package, you need the following steps:

Create a Github development token with package read permission.
Configure SSO for this token.
Configure your .npmrc file in your root directory:

//npm.pkg.github.com/:_authToken=XXX

@telefonica:registry=https://npm.pkg.github.com

Work on a master branch

When you work on a master branch, the libraries are published in npm.

To install the dependencies of a package, you need the following steps:

Request a npm token from your team.
Configure your .npmrc file in your root directory:

//registry.npmjs.org/:_authToken=XXXX

@telefonica:registry=https://npm.pkg.github.com

Docs:

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

Docker image

Description of how to create agent images, which is necessary for future deployment.

Introduction

The Docker image is the necessary component to deploy the agent in the ATRIA environment.

The image is built from the agent package and agent-server, which contains all the necessary to run the agent-server.

Build agent image

To build the agent image, it is necessary to use the docker command with the build option.

docker build -t <image_name> .

Where:

<image_name>: Name of the image to be created.
.: It indicates that the Dockerfile is in the current directory.

Dockerfile

The Dockerfile is the file that contains the instructions to build the image.

The Dockerfile for the agent image is located in the root directory of the agent package.

It is structured in two stages:

The first stage builds the agent package
The second stage creates the final image with the necessary dependencies and configurations and run the agent-server.

FROM python:3.13-slim AS base

ADD packages/atria-agent-dummy /opt/atria-agent
WORKDIR /opt/atria-agent

RUN pip install -r dev-requirements.txt && \
    python -m build

FROM python:3.13-slim

WORKDIR /opt/atria-agent

RUN apt-get update && apt-get install gcc python3-dev -y

COPY --from=base /opt/atria-agent/dist/atria_agent_dummy-*.tar.gz .
COPY --from=base /opt/atria-agent/entrypoint.sh entrypoint.sh
COPY --from=base /opt/atria-agent/version.txt version.txt

RUN pip install atria_agent_dummy-*.tar.gz && rm atria_agent_dummy-*.tar.gz

ENV AGENT_PACKAGE_NAME=atria_agent_dummy

ENTRYPOINT ["./entrypoint.sh"]

The directory atria-agent-dummy is the agent package that contains the agents code.

The entrypoint.sh script is used to run the agent server with the necessary configurations.

#!/bin/bash

set -e

export AURA_LOGGING_MODULE_VERSION=$(cat /opt/atria-agent/version.txt)

python -m atria_agents_server

Docs:

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

dapr-pubsub-service plugin

Description of the dapr-pubsub-service plugin

Introduction

The dapr-pubsub-service allows the interaction with the Dapr PubSub Service.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager

Provides components (IOC)

Name	Type	Description
daprPubSubApi	PluginType.API	Endpoints for the communication with Dapr
daprPubSubService	PluginType.Service	Manages the subscriptions of Dapr

Docs:

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

Develop a plugin and activate it in Aura Bridge

Guidelines for the generation of a new plugin and its activation/deactivation in Aura Bridge

Introduction

The process for the generation of a plugin and its activation or deletion in aura-bridge includes the following steps:

Plugin development

Install aura-development-cli (aucli)

To generate a new plugin, use aucli, a set of tools available in the “Command Line Interface” format to help you with development and testing.

How to use aucli?

Access the “help” command:

$ aucli bridge -h

Usage: aucli bridge [options] [command]

tasks associated with 'bridge' commands

Options:
  -h, --help      display help for command

Commands:
  generate        tasks associated with 'generate' commands
  help [command]  display help for command

Execute the following command in the aura-bridge project path:

$ aucli bridge generate plugin

✔ Whats the origin of the process? (ex.: Directline, Whatsapp, ...)? · channel1
✔ Whats the destination of the process? (ex.: Directline, Whatsapp, ...)? · channel2
✔ The name of processor is correct? (y/N) · true

The following files will be generated in aura-bridge:

added: src/plugins/channel1-channel2-processor/channel1-channel2-consume-services.ts
added: src/plugins/channel1-channel2-processor/channel1-channel2-controller.ts
added: src/plugins/channel1-channel2-processor/channel1-to-channel2-converter.ts
added: src/plugins/channel1-channel2-processor/error-to-channel2-api-converter.ts
added: src/plugins/channel1-channel2-processor/channel1-channel2-flow.ts
added: src/plugins/channel1-channel2-processor/index.ts
added: src/plugins/channel1-channel2-processor/package.json
added: src/plugins/channel1-channel2-processor/channel1-channel2-destination-channel2-response-error.ts
added: src/plugins/channel1-channel2-processor/channel1-channel2-utils.ts

Add a new swagger

Add a swagger inside your plugin in the path:
src/plugins/channel1-channel2-processor/swagger.yaml

openapi: 3.0.0
info:
  title: administration api to aura bridge
  description: Set of endpoints related to bridge administration
  version: 1.0.0
tags:
  - name: admin
    description: Bridge administration plugin
servers:
  - url: 'http://localhost:8045'
    description: Local server
  - url: 'https://svc-ap-current.auracognitive.com'
    description: ap-current
paths:
  /aura-services/v1/testing/channel1: # include the path to the new plugin
      get:
        tags:
          - testing-channe1
        description: channel1 testing.
        operationId: getChannel1Messages # controller function name.
        x-router-controller: plugins # in path src/controllers/plugins.ts
        responses:
          '200':
            description: OK
            headers: { }
          '500':
            description: An internal server error has occurred.

Add a new function controller

Add all the controllers in the path: src/controllers/plugins.ts

import Channel1Channel2Message from '../plugins/channel1-channel2-processor/channel1-channel2-controller';

export function getChannel1Messages(req: express.Request, res: express.Response) {
    Channel1Channel2Message.controller(req, res);
}

Plugin activation in Aura bridge

Every plugin to be loaded in aura-bridge must be defined in the plugin-config.json file.

⚠️ If this plugin has dependence with other plugins, they must also be added to the plugins list. If during the aura-bridge boot a plugin has a dependency with another not installed plugin, the bridge will fail in the boot process and will log an error indicating the lost dependency.

Add the plugin to the configuration file plugin-config.json (located at the root of the aura-bridge project):

[
    ...
    "./lib/plugins/channel1-channel2-processor",
    ...
]

Activate a new plugin during development

To activate a new plugin during development, it is only necessary to add the plugin path in the plugin-config.json file:

[
    "./lib/plugins/directline-service",
    "./lib/plugins/directline-whatsapp-processor",
    "./lib/plugins/whatsapp-incoming-processor",
    "./lib/plugins/whatsapp-service",
    // New plugin location here.
]

⚠️ take into account the dependencies with other plugins, as explained in the previous section.

Activate a new plugin for production

To add a new plugin in production, it is necessary to define the list of plugins using the plugin-config.json key in the aura-bridge ConfigMap for deployment in Kubernetes.

Example of aura-bridge ConfigMap using a configuration file:

apiVersion: v1
kind: ConfigMap
metadata:
  name: aura-bridge
  labels:
    app: aura-bridge
    stack: service
  namespace: {{ kubernetes_core_namespace }}
data: 
  plugin-config.json: |
    {{ lookup('file','<FOLDER_PATH>/plugin-config.json',convert_data=False) | indent(4,indentfirst=False) }}

Plugin removal in Aura bridge

To remove a plugin, it is only necessary to delete the plugin path in the plugin-config.json file.

⚠️ In order to eliminate a plugin correctly, it is necessary to verify that no other plugins from those installed depends on the one we want to eliminate.

Docs:

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

Develop a filter for Engine Filter API

Guidelines for the knowledge and generation of filters for Engine Filters API.

Introduction

A filter is a set of configurations and instructions that allow data to be grouped and queried in order to determine whether the flow of a use case should be changed at a given time. For example, if we have a use case that queries an LLM, we can create a filter to limit the use of these LLMs by user, or by channel at a given time. For this documentation we are going to make a filter that limits the use of LLMs by user and use case, we will describe it later.

Engine Filter API

Anatomy of a filter

A filter is composed of a descriptive part, a configuration part, and an execution instruction part. Both parts are stored in JSON format. The service in charge of the storage is the Aura Configuration API. [TODO url]. The execution part is done by MongoDB instructions.

Descriptive Properties

Field name	Type	Required	Description
id	string	true	UUID that uniquely identifies a routing filter in Aura.
name	string	true	Name that uniquely identifies a routing filter in Aura.
description	string	false	Routing Filter description.
type	string	true	Contains the type of filter. Currently, there is only one type ‘userId’.

    {
        "name": "preset-filter-stb-conversational-search",
        "id": "4a879583-5f76-4e6b-87c1-6250e8743dda",
        "description": "Limit the number of messages per user in a month for stb conversational search preset",
        "type": "userId"
        ....
    }

Configuration Properties

Field name	Type	Required	Description
entities	string[]	true	Contains at least one entity necessary to generate the data for the filter.
dataBase	object	true	Contains an object with the collections necessary to store and process data. See database object.
vars	object	true	Contains an object with the custom variables necessary for any phase of the filter. Encrypted field.
fields	object	true	Contains the field mapping for grouping and its relationship with the previously defined entities. Encrypted field.
sourceFilters	object	false	Contains an object to filter source data when loading from entity data. Encrypted field.

    {
        ....
       "entities": [
            "GATEWAYMESSAGE"
        ],
        "vars": {
            "llm_execution_limit": 10
        },
        "dataBase": {
            "dataFilterCollection": {
                "collectionName": "dataFilterPreset",
                "expiration": 5356800,
                "indexes": [
                    {
                        "seqId": 1
                    }
                ]
            },
            "dataSummaryCollection": {
                "collectionName": "dataSummaryStbConvSearch",
                "expiration": 5356800,
                "indexes": [
                    {
                        "month": 1,
                        "total": 1,
                        "year": 1
                    },
                    {
                        "itemId": 1,
                        "month": 1,
                        "year": 1
                    }
                ]
            }
        },
        "fields": {
            "MatchingValue": "^ef3d0603-3fef-4109-a577-0ab92f9060df$",
            "forId": "USER_ID",
            "forMatchingField": "AURA_PRESET_NAME",
            "forTime": "MESSAGE_TM"
        },
        "sourceFilters": [
            {
                "field": "USER_ID",
                "op": "notEqual",
                "val": ""
            }
        ],
        ....
    }

Execution Properties

Field name	Type	Required	Description
match	object	true	Contains an object with the MongoDB aggregation format that must return grouped data. Encrypted field.
summary	object	true	Contains an object with MongoDB command format to insert these obtained aggregates into a summary collection. Encrypted field.
actions	object[]	true	Contains an array of objects with the actions to be performed on the filtered data.
summaryFilter	object	true	Contains an object with MongoDB command format to select the records that meet the filter. Encrypted field.

...
 "match": [
            {
                "$match": {
                    "fieldForMatch": "{{fields.forMatchingField}}",
                    "seqId": {
                        "$gt": "{{ctx.lastSeqId|number}}"
                    },
                    "valueForMatch": {
                        "$options": "i",
                        "$regex": "{{fields.MatchingValue}}"
                    }
                }
            },
            {
                "$group": {
                    "_id": {
                        "itemId": "$itemId",
                        "month": "$month",
                        "year": "$year"
                    },
                    "seqId": {
                        "$max": "$seqId"
                    },
                    "total": {
                        "$sum": 1
                    }
                }
            },
            {
                "$project": {
                    "_id": 0,
                    "itemId": "$_id.itemId",
                    "month": "$_id.month",
                    "seqId": 1,
                    "total": 1,
                    "year": "$_id.year"
                }
            }
        ],
        "summary": {
            "filter": {
                "itemId": "{{doc.itemId}}",
                "month": "{{doc.month|number}}",
                "year": "{{doc.year|number}}"
            },
            "options": {
                "upsert": true
            },
            "update": {
                "$inc": {
                    "total": "{{doc.total|number}}"
                },
                "$set": {
                    "expiresAt": "{{ctx.expiration|expires}}",
                    "month": "{{doc.month|number}}",
                    "updatedAt": "{{__DATE_NOW__}}",
                    "year": "{{doc.year|number}}"
                }
            }
        },
        "summaryFilter": {
            "filter": {
                "month": "{{ctx.month|number}}",
                "total": {
                    "$gt": "{{vars.llm_execution_limit|number}}"
                },
                "year": "{{ctx.year|number}}"
            },
            "options": {
                "projection": {
                    "_id": 0,
                    "itemId": 1,
                    "month": 1,
                    "total": 1,
                    "year": 1
                }
            }
        }

Create, execute and check a filter

To see all the steps necessary to create and use the filter, let’s use the example we discussed in the introduction.

Let’s suppose that we need a filter so that the users have a limit of access to the LLM APIs per use case. We are going to set a limit of 150 interactions per month. And this filter should reset those results at the beginning of each month.

Create a filter. Steps

Filters use data generated for KPIs, so the most important thing before starting to define a filter, is to know which entity has all the necessary fields to be able to extract the necessary conditions for the filter. Note that currently only one Entity can be used per filter, in later versions this may change and support multiple entities.

For our example we will identify what data we need

Date of interaction
User identifier Preset identifier

For our filter the only entity that contains all these data is GATEWAYMESSAGE

Iteration date -> MESSAGE_TM User ID -> USER_ID Preset identifier -> AURA_PRESET_NAME The value of the preset to which we are going to add the filter will be: “ef3d0603-3fef-4109-a577-0ab92f9060df”.

Once the Entity has been identified we proceed to create the descriptive part of the filter.

        "name": "preset-filter-for-users",
        "id": "1a879583-5f76-4e6b-87c1-6250e874bbs",
        "description": "Limit the number of messages per user in a month for LLM User Case",
        "type": "userId"

As we have the entity we are going to use we set it:

       "entities": [
            "GATEWAYMESSAGE"
        ]

We associate the identified fields in the CSV.

        "fields": {
            "MatchingValue": "ef3d0603-3fef-4109-a577-0ab92f9060df",
            "forId": "USER_ID",
            "forMatchingField": "AURA_PRESET_NAME",
            "forTime": "MESSAGE_TM"
        }

We will set the limit to 150 and put it in a variable.

        "vars": {
            "llm_execution_limit": 150
        }

As the USER_ID field is optional, we will filter out those records that do not have USER_ID, i.e. USER_ID notEqual "". This is done in the sourceFilters property. Although it is an array, it currently supports only one element. The available operators are: major, minor, equal and notEqual. SourceFilters also supports other data types for comparison, such as date or number. This is set with the cast: number|date property, otherwise the default is string.

     "sourceFilters": [
            {
                "field": "USER_ID",
                "op": "notEqual",
                "val": ""
            }
        ]

We will need to name the collections and the lifetime of the data in seconds.

      "dataBase": {
            "dataFilterCollection": {
                "collectionName": "dataFilterPreset",
                "expiration": 5356800
            },
            "dataSummaryCollection": {
                "collectionName": "dataSummaryFilterPreset",
                "expiration": 5356800
        }

We have already established all the values for the descriptive part and the configuration part, we must take into account that when we finish defining the execution part we will have to add some more data, such as indexes, if we want the filter execution to be done with the maximum performance.

Create Execution definition

Once a filter has been created, the KPI utilities will already know which entities have to send the Engine Filter API in order to process and group data and then validate the filters with them.

In our example, in order to group those data we need the dataFilterCollection collection that will contain the raw data extracted from the KPIs entity.

  "forId": "USER_ID",                     -> itemId
  "forMatchingField": "AURA_PRESET_NAME", -> fieldForMatch and valueForMatch
  "forTime": "MESSAGE_TM"                 -> year, month, expires and seqId

Example:

{
    "seqId" : 1756883926388.0,                                   -> Timestamp to generate partial summaries
    "itemId" : "IN-ewXp7S8u4mL0RlKJStA",                         -> UserId
    "year" : 2025,                                               -> Year
    "month" : 8,                                                 -> Month 
    "fieldForMatch" : "AURA_PRESET_NAME",                        -> fieldForMatch         
    "valueForMatch" : "a652we235-3fef-4109-a577-0909d8ef234567", ->valueForMatch
    "expiresAt" : "2025-09-03T07:20:15.388Z"                     -> expiration date
}

In our example we have to look for those that have the valueForMatch equal to the one defined in fields MatchingValue and group the data by userId, month, year, counting the number of iterations, i.e. we are looking for something like this:

{
    "month" : 8,
    "itemId" : "bk3iI3GwQWO2-4YI0etc0w",
    "year" : 2025,
    "expiresAt" : "2025-09-04T09:13:48.345Z",
    "total" : 40
}

Before we start defining the execution properties, let’s explain the format in which they are defined.

JSON with PLACEHOLDERS

The JSON that compose the properties with execution parameters have placeholders to be able to inject variables and other values that have other properties.

Prefixes

vars: Refers to the properties defined inside the vars object. Example ````vars.llm_execution_limit``` in our example will have the value 150.
fields: Refers to the properties defined inside the fields object. Example: ````fields.MatchingValue```.
doc: It refers to the document returned by mongodb in the previous execution. It will only appear in the summary property since it is formed with the results of a previous query. Example: ````doc.itemId```. In order to use these properties they must be inside the $project property of the match property.
ctx: Contains variables that can be used to insert in execution properties, these are:
- ctx.day: Today’s day.
- ctx.month: Current month.
- ctx.year: Current year.
- ctx.lastSeqId: Last seqId processed to create summaries.
- ctx.expiration: Expiration time of the data to be generated.

Data Types

number: Numeric, integer or float type. Example: {{ctx.month|number}}.
date: Date type. Example: {{var.EDate|date|date}}.
expires: Current date + placeholder value. Example: {{ctx.expires|expires}}.
boolean: Boolean. Example: {{{var.isTrue|boolean}}.
string: String, if nothing is set it is the default string. Example: {{doc.itemId}} or {{doc.itemId|string}} .
lower: String in lowercase. Example: {{doc.itemId|lower}}.
upper: String in uppercase. Example: {{doc.itemId|upper}}.
trim: Removes whitespace from a string. Example: {{doc.itemId|trim}}.

Variables
- _DATE_NOW_: Contains the current date. Example: "updatedAt":"{{__DATE_NOW__}}".

Create execution properties: match, summary and summaryFilter

Once we have data in the raw data collection what we need is

1.- Get the data that has not been processed yet filtering by a certain condition and grouping them in this case by ItemId, month, year, and finally returning a data model to generate the summaries. This is achieved in the match property:

Step A: $match. Select data to filter by a regex.


"$match": {
    "fieldForMatch": "{{fields.forMatchingField}}",
    "seqId": {
        "$gt": "{{ctx.lastSeqId|number}}"
    },
    "valueForMatch": {
        "$options": "i",
        "$regex": "{{fields.MatchingValue}}"
    }
}

In our case this would be to select those elements that the field “AURA_PRESET_NAME” has the value “ef3d0603-3fef-4109-a577-0ab92f9060df” and whose seqId is greater than the last processed seqId.


"$match": {
    "fieldForMatch": "AURA_PRESET_NAME",
    "seqId": {
        "$gt": "1099288387374"
    },
    "valueForMatch": {
        "$options": "i",
        "$regex": "ef3d0603-3fef-4109-a577-0ab92f9060df"
    }
}

Step B: $group. We group by itemId, month and year. We store the last seqId in $max.


"$group": {
   "_id": {
       "itemId": "$itemId",
       "month": "$month",
       "year": "$year"
   },
   "seqId": {
       "$max": "$seqId"
   },
   "total": {
       "$sum": 1
   }
}

This will be grouping the data, adding the matching elements and obtaining the maximum seqId used. The latter will be stored in ctx.lastSeqId.

Step C: $project. We return the grouped data to update or create the elements in the summary collection.


"$project": {
    "_id": 0,
    "itemId": "$_id.itemId",
    "month": "$_id.month",
    "seqId": 1,
    "total": 1,
    "year": "$_id.year"
}

2.- We update or create the grouped data, this is included in the summary property.


"summary": {
    "filter": {
        "itemId": "{{doc.itemId}}",
        "month": "{{doc.month|number}}",
        "year": "{{doc.year|number}}"
    },
    "options": {
        "upsert": true
    },
    "update": {
        "$inc": {
            "total": "{{doc.total|number}}"
        },
        "$set": {
            "expiresAt": "{{ctx.expiration|expires}}",
            "month": "{{doc.month|number}}",
            "updatedAt": "{{__DATE_NOW__}}",
            "year": "{{doc.year|number}}"
        }
    }
}

The doc prefix refers to the result of the previous execution of match. Once the summary has been executed, we will already have in the dataSummaryCollection data to query if they comply or not with the filter.

3.- Obtain the data that meet the filter. summaryFilter


"summaryFilter": {
    "filter": {
        "month": "{{ctx.month|number}}",
        "total": {
            "$gt": "{{vars.llm_execution_limit|number}}"
        },
        "year": "{{ctx.year|number}}"
    },
    "options": {
        "projection": {
            "_id": 0,
            "itemId": 1,
            "month": 1,
            "total": 1,
            "year": 1
        }
    }
}

In this case it looks for records that comply with the current month and year and that exceed the limit configured in vars.llm_execution_limit. The filter engine API stores the elements that exceed the filter in a cache each time the dataSummaryCollection is updated.

Check filters

Filters can be queried via Configuration API calls: https://ENV.auracognitive.com/aura-services/v2/routing-filters/FILTER_ID/items/ITEM_ID, or within a context filter.

Example:

{
  "name": "tvCustomRecommendation",
  "dialogs": [
    {
      "id": "tv-custom-recommendation",
      "onlyIn": [
        "set-top-box"
      ],
      "allowAnonymous": true,
      "triggerConditions": [
        {
          "intent": "intent.tv.custom_recommendation",
          "contextFilters": [
            {
              "name": "limit-num-messages-LLM-user",
              "type": "RoutingByFilter",                             <-- Set the type
              "conditions": "4a879583-5f76-4e6b-87c1-6250e8743dda",  <-- FilterId
                "name": "send-custom-messsage",
                "breakDialogExecution": true,
                "breakFilterEval": true,
                "redirectToIntent": "intent.send-custom-message",
                "resource": "intent.send-custom-message:default.message",
                "removeBypass": true,                                <-- Remove bypass
                "suggestions": false
              }
            }
          ],
          "settings": {
            "action": "noAction",
            "sound": "positive",
            "type": "common"
          }
        }
      ],
      "bypass": {
        "duration": 4,
        "payloadName": "openai",
        "initialData": {},
        "recognizersEnabled": true,
        "recognizersBreakIntents": {
          "intent.tv.display": [
            "[Display Channel]",
            "[Display Contents]"
          ],
          "intent.navigation.section_show": [
            "[Sections]"
          ]
        }
      }
    },

To include a filter inside a context filter the following properties must be included:

type: Must have the type “RoutingByFilter “.
conditions: It must have the id of the Filter we want to consult.

If the dialog has an associated Bypass it is important to add “removeBypass”: true inside the “true “ property.

Docs:

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

Stages in use cases development over Aura NLP

Guidelines that describe the orderly steps required for the development of a use case over Aura NLP, with the objective of making Aura understand the users’ utterances.

Introduction

These steps correspond to 3 main overall stages:

Build the understanding model and train it, that is, teach Aura to understand
Test the model through an ongoing and cyclical process until the accuracy in terms of intents and entities recognition is good enough
Certify the model and publish it

Prerequisites

Firstly, check that all the prerequisites are fulfilled:

Technical resources are available
Aura NLP Virtual Machine is installed and working
NLP data repository local branch is generated

1. Build up the NLP dynamic pipeline

For the development of a new use case, you must design a dynamic pipeline (pipeline.json file) through the most appropriate combination of stages and connectors for the recognition of intents and entities in the use case.

For this purpose, follow the guidelines in the succeeding sections.

1.1. Select the elements composing your NLP pipeline

Select the elements composing the pipeline (stages, connectors, normalization pipelines) depending on the recognition process required for the use case and its associated channel, and combine them for the design of the NLP pipeline.

Catalog of components for NLP pipelines

1.2. Generate the pipeline.json file

The base file for the dynamic pipeline is pipeline.json, that must be generated in the following path from the NLP repository:
aura-nlpdata-[country_code]/data/[language]/[channel]/pipeline.json

Edit this file including the required fields from all your selected stages and connectors and indicating the hierarchy between them:

name: Unique string that identifies the pipeline.
initial_node_id: Key of the element where the pipeline starts. It must appear as the first one also in the fields elements and links.
elements: Include in this field each element composing the pipeline (stages and connectors) and characterize them with two attributes:
- type: Two feasible values:
  - stage: pipeline stage.
  - joint: connector between pipeline stages.
- classpath: Class path of the specific element, that is, Python class reference from the root directory that must be included in order to use this stage.
  To obtain the classpath of each element of your pipeline:
  - Access to the NLP catalog of components
  - Look for your specific stage, connector or normalization pipeline
  - Copy the classpath in the corresponding Path section. Take into account:
  - The name of the element is free, but it should be auto-descriptive of its content.
  - The first element must be the one specified in initial_node_id.
  - The elements must be ordered: after a parent, its children must be included.
args: This field is only required for the configuration of three NLP components: Length Adapter; Domain Selector connector; Disambiguation connector
links: This field includes the hierarchy of the pipeline and connections between its elements.
- Each link item contains the connectors (as keys) and their children are the stages or other connectors they deal with.
- Each key in links must be of joint type.

See below a practical examples of the pipeline.json file:

Example 1. Garua pipeline.json file

The pipeline hierarchy can be seen in the boxes that contain other elements (PygrapeCanlaonPipeline and AcotangoNothresholdPipeline). Diamond boxes represent joint stages in the pipeline.

{
  "name": "Garua",
  "initial_node_id": "GaruaPipeline",
  "elements": {
    "GaruaPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
    "FromConfigNormalizerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.normalizer_wrapper.from_config_normalizer_wrapper.FromConfigNormalizerWrapper"
    },
    "PygrapeGrammarWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.grammar_wrapper.pygrape_grammar_wrapper.PygrapeGrammarWrapper"
    },
    "AcotangoNoThresholdPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
    "StandardNerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.ner_wrapper.standard_ner_wrapper.StandardNerWrapper"
    },
    "FullEntityORDCCLUPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.joint.conditionals.OrPipeline"
    },
    "FullEntityRecognizerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.recognizer_wrapper.full_entity_recognizer_wrapper.FullEntityRecognizerWrapper"
    },
    "DCCLUPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
    "DomainClassifierWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.domain_classifier_wrapper.domain_classifier_wrapper.DomainClassifierWrapper"
    },
    "CluRecognizerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.recognizer_wrapper.clu_recognizer_wrapper.CluRecognizerWrapper"
    },
    "EntityTaggerAdapterWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.entity_tagger_adapter_wrapper.EntityTaggerAdapterWrapper"
    },
    "StandardThresholdWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.standard_threshold_wrapper.StandardThresholdWrapper"
    },
    "NoneHandlerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.none_handler_wrapper.NoneHandlerWrapper"
    },
    "ExactMatchOrRestStages": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.joint.conditionals.OrPipeline"
    },
    "ExactMatchRecognizerWrapper": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.recognizer_wrapper.exact_match_recognizer_wrapper.ExactMatchRecognizerWrapper"
    }
  },
  "links": {
    "GaruaPipeline": [
      "FromConfigNormalizerWrapper",
      "ExactMatchOrRestStages",
      "EntityTaggerAdapterWrapper",
      "StandardThresholdWrapper",
      "NoneHandlerWrapper"
    ],
    "ExactMatchOrRestStages": [
      "ExactMatchRecognizerWrapper",
      "PygrapeGrammarWrapper",
      "AcotangoNoThresholdPipeline"
    ],
    "AcotangoNoThresholdPipeline": [
      "StandardNerWrapper",
      "FullEntityORDCCLUPipeline"
    ],
    "FullEntityORDCCLUPipeline": [
      "FullEntityRecognizerWrapper",
      "DCCLUPipeline"
    ],
    "DCCLUPipeline": [
      "DomainClassifierWrapper",
      "CluRecognizerWrapper"
    ]
  }
}

Example 2. Configuration for the stage Length Adapter

See below an example of how to integrate this stage in a pipeline:

{
  "name": "Example",
  "initial_node_id": "ExamplePipeline",
  "elements": {
    "ExamplePipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
    "LengthAdapterThreshold": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.length_adapter_wrapper.LengthAdapterWrapper",
      "args": {
         "max": 50,
         "min": 1,
         "intent_template": "intent.example"
      }
    }
  },
  "links": {
    "ExamplePipeline": [
      "LengthAdapterThreshold"
    ]
  }
}

The following snippet shows how to configure more than one stage of the Length Adapter to return different intents for max or min length characters.

  "name": "Example",
  "initial_node_id": "ExamplePipeline",
  "elements": {
    "ExamplePipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
    "LengthAdapterMaxThreshold": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.length_adapter_wrapper.LengthAdapterWrapper",
      "args": {
        "max": 50,
        "intent_template": "intent.max.example"
      }
    },
    "LengthAdapterMinThreshold": {
      "type": "stage",
      "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.length_adapter_wrapper.LengthAdapterWrapper",
      "args": {
        "length_threshold_map": {
          "min": 1,
          "intent_template": "intent.min.example"
        }
      }
    }
  },
  "links": {
    "ExamplePipeline": [
      "LengthAdapterMaxThreshold",
      "LengthAdapterMinThreshold"
    ]
  }
}

1.3. Validate your pipeline.json file

At this stage, it is recommended to validate the generated pipeline.json file in order to assure that it is consistent and that all stages and joint operations are correctly related.

For this purpose, the following verifications are recommended:

Each item of links includes dicts, where the key is a name and the values are lists of class names.
Each item of elements has type and classpath.
initial_node_id is a key in links.
Each key in links is a joint stage (by having type equals to joint in elements).
Each class belonging to the values of a links item is present in elements.

Different examples of invalid pipeline.json files

Invalid pipeline as WrongPipeline key does not have a list of class names in links section:

{
   "name": "WrongPipelineExample",
   "initial_node_id": "WrongPipeline",
   "elements": {
     ...
   },
   "links": {
     "WrongPipeline":"DCCLUPipeline",
     "DCCLUPipeline": [
       "DomainClassifierWrapper",
       "CluRecognizerWrapper"
     ]
   }
 }

Pipeline contains an element without type:

{
  "name": "WrongPipelineExample",
  "initial_node_id": "WrongPipeline",
  "elements": {
    "WrongPipeline": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
   "DCCLUPipeline": {
      "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
    },
...

Pipeline MissingPipeline is not included as a key in the field links:

{
   "name": "WrongPipelineExample",
   "initial_node_id": "MissingPipeline",
   "elements": {
     ...
   },
   "links": {
     "WrongPipeline": [
      "DCCLUPipeline",      
      "EntityTaggerAdapterWrapper",
       "StandardThresholdWrapper",
       "NoneHandlerWrapper"
     ],
     "DCCLUPipeline": [
       "DomainClassifierWrapper",
       "CluRecognizerWrapper"
     ]
   }
 }

Pipeline with a stage (DomainClassifierWrapper) as key in links and not a joint:

{
   "name": "WrongPipelineExample",
   "initial_node_id": "WrongPipeline",
   "elements": {
     "WrongPipeline": {
       "type": "joint",
       "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
     },
    "DCCLUPipeline": {
       "type": "joint",
       "classpath": "auracog_pipelines.pipelines.base.BasePipeline"
     },
    "DomainClassifierWrapper": {
       "type": "stage",
       "classpath": "auracog_pipelines.stage_wrappers.domain_classifier_wrapper.domain_classifier_wrapper.DomainClassifierWrapper"
     },
     "CluRecognizerWrapper": {
       "type": "stage",
       "classpath": "auracog_pipelines.stage_wrappers.recognizer_wrapper.clu_recognizer_wrapper.CluRecognizerWrapper"
     },
     "EntityTaggerAdapterWrapper": {
       "type": "stage",
       "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.entity_tagger_adapter_wrapper.EntityTaggerAdapterWrapper"
     },
     "StandardThresholdWrapper": {
       "type": "stage",
       "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.standard_threshold_wrapper.StandardThresholdWrapper"
     },
     "NoneHandlerWrapper": {
       "type": "stage",
       "classpath": "auracog_pipelines.stage_wrappers.adapter_wrapper.none_handler_wrapper.NoneHandlerWrapper"
     }
   },
   "links": {
     "WrongPipeline": [
      "DCCLUPipeline",      
      "EntityTaggerAdapterWrapper",
       "StandardThresholdWrapper",
       "NoneHandlerWrapper"
     ],
     "DCCLUPipeline": [
       "DomainClassifierWrapper",
       "CluRecognizerWrapper"
     ],
    "DomainClassifierWrapper": [
       "CluRecognizerWrapper"
     ] 
  }
 }

2. Configure your NLP model

It is required to configure every element composing the NLP pipeline:

All NLP stages (excepting Length Adapter) and normalization pipelines are configured in the file nlp.json file for each language and channel placed in the [NLP repository]:
aura-nlpdata-[country_code]/config/etc/nlp_config/nlp.json
As an exception, Length Adapter stage, Domain Selector connector and Disambiguation connector need a specific configuration in the file pipeline.json(args field) placed in the [NLP repository]:
aura-nlpdata-[country_code]/data/[language]/[channel]/pipeline.json

To obtain the configuration of each element of your pipeline:
- Access to the NLP catalog of components
- Look for your specific stage, connector or normalization pipeline
- Copy the classpath in the corresponding Configuration section.
If dictionaries are included in the NLP model, they must be also configured:
- Configuration of dictionaries.

3. Define your data resources

Every NLP stage needs particular resources for its training and testing that must be generated through the edition of a specific file for each of them.

3.1. Generate the files for each NLP stage

Generate the specific file for each stage composing your NLP pipeline and for each language and channel.
- Access to the NLP catalog of components
- Look for your specific stage
- Find in the Files section the specific files required for this stage
- Edit them
Place these files in:
aura-nlpdata-[country_code]/data/[language]/[channel], where:
- language corresponds to the culture code of all the languages supported by Aura (e.g., es-es, en-gb, de-de, pt-br).
- The channel variable in the pattern is the channel code used to identify the specific channel (for example, mh (Movistar Home), mp (Movistar Plus)).

3.2. Generate dictionaries

If your NLP pipeline contains entities recognition stages (Entity Tagger Adapter; Standard NER and Gazetteer NER), it is needed to use the dictionaries sdict_items.json and sdict_aliases.json which are automatically generated from two sources: manual catalogs and/or URM data.

Learn how to do it in generation of Aura NLP dictionaries.

4. Define your end-to-end tests

E2E test files perform the evaluation of accuracy in the recognition of domains, intents and entities, with two approaches:

Measurement of the overall accuracy of the pipeline (mandatory)
Measurement of the accuracy of the different stages of the pipeline (optional)

Once generated, when running the corresponding pipeline with the user’s utterance as the pipeline input, the system will compare the result provided by the pipeline with the expected values declared in the file (intent, entities and domain) to calculate the pipeline accuracy.

4.1. Define E2E test set files

You must define a file for the end-to-end evaluation of the system as well as regression tests: testset.json and regression.json. They both are dictionaries with the same structure:

phrase: Statement (sentence, phrase or isolated word) to be tested.
domain: Inferred domain for the user’s utterance. Possible values:
- <domain_name>: name of the identified domain.
- null: when domain is not of application.
- default: in case there is only one domain or in case the grammar engine recognizes the whole utterance.
  ⚠️ The value for the field domain must be included using quotation marks for every value excepting for null.
intent: Expected intent.
options: List of .json containing certain packages of intents and entities to disambiguate (optional field).
entities: Expected entities. It is a list of json with the following fields:
- value: entity value to be recognized.
- e_type: entity type expected.
- start_index: Initial position of the entity in the filled phrase.
- end_index: final position of the entity in the filled phrase.
- canon: expected canon for a given entity. If canon is deactivated or the entity recognizer does not work with canon, this field must be completed with the same value of the field value but normalized (e.g., “Film”, value: Film; canon: film).
  - This field is currently used in Spain for those use cases related to TV content searches (e.g., “search for films”) in which there are specific codes (labels) for searching particular content types that the API needs to find in the corresponding catalogs to resolve the petition.
  - For instance, in the utterance “I want to watch an action movie”, “movie” is the value of the entity whereas “movies” may be its canon and “MV” the label the API needs to find this type of content in the catalogs. The same could be applied to the genre “action”.
- label: expected label. It can have the value null. The same use as canon is currently applied.

4.1.1. testset.json

At this stage, you should define the testset.json file in: pipeline_eval/ob/[country_code]/resources/[language]/[channel]/testset.json

It must include the testing statements for the E2E evaluation of the system’s accuracy (sentences or isolated words) and in order to identify potential problems (e.g., unmatching, low confidence/score).

You can generate different testset.json files for different purposes, for instance, for evaluation of metrics or to carry out regression tests at a later stage. To calculate the metrics, all the different files are considered as a unique one.

Example of testset.json file:

[
  {
    "phrase": "put the film Coco",
    "domain": "default",
    "intent": "intent.tv.search",
    "entities": [
      {
        "value": "Coco",
        "e_type": "ent.audiovisual_film_title",
        "start_index": 13,
        "end_index": 17,
        "canon": "coco",
        "label": null
      }
    ],
   "options": []
  },
  {
    "phrase": "show me my bill",
    "domain": "default",
    "intent": "intent.billing.check",
    "entities": [
      {
        "value": "bill",
        "e_type": "ent.bill",
        "start_index": 12,
        "end_index": 15,
        "canon": "bill",
        "label": null
      }
    ],
    "options": []
  }
]

4.1.2. regression.json

Define your regression.json file in the path: pipeline_eval/ob/[country_code]/resources/[language]/[channel]/regression.json

It may include crucial functionalities that must work in the system or other key checks that are not included in testset.json. The purpose is to verify that modifications do not impact in existing features and to prevent the system from bugs.

Previously executed test cases are re-executed in order to verify the impact of a change.

4.2. Define stage-specific E2E test set files

ℹ️ This is an optional step if you want to include specific E2E tests for the evaluation of an isolated stage in the testing batch.

You can create specific E2E testsets files for the evaluation of an isolated stage. It is done adding phrases that must be solved by this specific stage in order to ensure that the end-to-end evaluation is representative for that stage and avoid tests that do not evaluate it.

Currently, this is only available for the OpenAI embeddings recognizer stage.

For the definition of specific E2E tests for this stage, follow these instructions:

Define specific phrases to be resolved by the OpenAI embeddings recognizer stage.
Execute the script build_local_testset.sh in:
aura-nlpdata-[country_code]/tools/build_local_testset.sh
Once executed, it creates a stage-specific testset.json file in the path: tmp_testsets/[country_code]/resources/[language]/[channel]/
Although the name of the file can never be modified, it is possible to modify its content, as long as its structure is respected, adding new test sentences or eliminating them.
To be able to use these E2E test, copy it in the following path for it to be packaged with the general testset.json file: pipeline_eval/ob/[country_code]/resources/[language]/[channel]/

4.3. Best practices for the definition of E2E test set files

All intents should be represented within all the existing test testset.json files.
Firstly, generate a battery of statements for the use case, taking into account its semantic complexity. After that, divide all the generated statements into three groups in the way that statements in the training set are not included in the test sets and vice versa:
- Training set
- Specific NLP stage test set
- E2E test set
Follow this pre-established ratio between training and testing statements: each intent must satisfy that the number of test statements is, at least, 20% of the total statements (training and test statements).
Depending on the specific NLP stages, the number of recommended testing statements must be representative. In general terms, and only as a guidance, the number of testing statements can be as follows:
- Only CLU: 20% of statements in CLU training
- CLU + Grammar: 20% of statements in CLU training
- Only Grammar: 3 statements
- More than 1 use case on an intent: 30 statements per use case.
The testing statements provided by the Product Team and/or UX Team must be included, as prototypical of a given use case.
The statements must include different variations (for example, with/without entities, etc.).
Keys of the testset.json file should be ordered from generic to specific ones:

        { 
            "phrase": "Search the film Frozen", 
            "domain": "domain.tv", 
            "intent": "intent.tv.search", 
            "entities": [],
            "options": []
        },

The end-to-end test set is specific for each of the potential channels, as some use cases can be implemented in certain channels but not in others.
The field options is optional and only included when disambiguation is considered.
In case that, due to non-satisfactory results during the evaluation process, a re-training is required, linguists should check that all the modifications are included in the E2E tests.
In case roles are defined in entities for their recognition through the Grammar stage, they do not affect to the E2E tests (See more information regarding roles in Grammars in recognition of utterances with several entities in Grammars.

5. Train your understanding model

Once all the resources for each stage of the pipeline have been generated, you have to launch the training process in order to compare the testing batch against the training model.

For this purpose, the aura-nlpdata-[country_code]/tools folder of the NLP repository includes bash scripts, described in the following sections.

It is important to mention that the NLP system can be locally trained in an intelligent way, meaning that only the stages that have been modified (from a last training) are trained again, thus making the process much more efficient.

5.1. Set up configuration properties

Go the the path: aura-nlpdata-[country_code]/tools/build_local_variables.sh.tpl
This file is a template used for configuration purposes, specifically for defining CLU connection parameters. To setup these properties, copy this file to a new one named build_local_variables.sh, removing the .tpl extension.
Fill in the config variables included in this file with the local credentials, as explained below.
This file is automatically ignored by git because it has been included in the .gitignore file, thus it must not be included manually.

The parameters to fill in the build_local_variables.sh script are shown below:

#!/usr/bin/env bash

# BUILD_LOCAL AND RUN_WEB_TRAININGS
export AZURE_NLP_MODELS_URL=""
export OAI_ID_SUBSCRIPTION=""
export OAI_RESOURCE_GROUP=""
export OAI_ACCOUNT_NAME=""
export OAI_AZURE_TOKEN_CLIENT_ID=""
export OAI_AZURE_TOKEN_CLIENT_SECRET=""
export OAI_AZURE_TOKEN_TENANT=""
export OAI_USER=""
export RESOURCE_NAME_OPENAI=""
export QDRANT_URL=""
export QDRANT_API_KEY=""
export CLU_SUBSCRIPTION_KEYS=""
export CLU_RESOURCE_NAME=""
export CLU_USER=""
export CLU_STORAGE_SUBSCRIPTION_KEYS=""
export CLU_STORAGE_RESOURCE_NAME=""

# RUN_WEB_TRAININGS
export GITHUB_TOKEN=""
export GITHUB_USER=""
export REPO_OWNER=""
export TRAINING_WEB_AZURE_BASE_URL=""
export TRAINING_WEB_AZURE_SAS_TOKEN=""

# BUILD_CATALOGS
export LANGUAGE=""
export CHANNEL_LIST=""
export AZURE_CATALOGS_ACCOUNT_NAME=""
export AZURE_CATALOGS_TOKEN=""

export AWS_CATALOGS_ACCESS_KEY=""
export AWS_CATALOGS_SECRET_KEY=""
export CATALOGS_RESOURCES_CONTAINER=""
export CATALOGS_RESOURCES_PROVIDER=""

The required variables are described below:

AZURE_NLP_MODELS_URL: URL for the Azure NLP models container.
GITHUB_TOKEN: Variable only required for ABACUS. Personal token provided by GitHub for secure authentication.
GITHUB_USER: Variable only required for ABACUS. Name of Github user.
REPO_OWNER: Variable only required for ABACUS. Name of the owner of the repository. Value: Telefonica.
TRAINING_WEB_AZURE_BASE_URL: Variable only required for ABACUS. URL base to get web package. It is provided by APE Team.
TRAINING_WEB_AZURE_SAS_TOKEN: Variable only required for ABACUS. SAS token with the required permission granted. It is provided by APE Team.
OAI_ID_SUBSCRIPTION: Azure OpenAI subscription ID. It can be obtained from the subscription website.
OAI_RESOURCE_GROUP: Name of resource group in Azure where the OpenAI applications are created.
OAI_ACCOUNT_NAME: Name of OpenAI resource to be used.
OAI_AZURE_TOKEN_CLIENT_ID: Client ID of Azure Portal – App registration page assigned to your app.
OAI_AZURE_TOKEN_CLIENT_SECRET: Application secret created in the app registration portal.
OAI_AZURE_TOKEN_TENANT: Value that indicates who can sign into the application.
OAI_USER: Parameter to identify the user of OpenAI application. It is unique for each developer in order not to overlap the OpenAI trainings. This value is used to create database collections.
RESOURCE_NAME_OPENAI: Name of resource to be used.
QDRANT_URL: URL of Qdrant service. In the virtual machine, it is http://localhost:6333.
QDRANT_API_KEY: APIkey of Qdrant service. In the virtual machine, it is void.
CLU_SUBSCRIPTION_KEYS: Parameter provided by CLU to create applications.
CLU_RESOURCE_NAME: Name of resource to be used.
CLU_USER: Parameter to identify the user of CLU application. It is unique for each developer in order not to overlap the CLU trainings.
CLU_STORAGE_RESOURCE_NAME: Name of shared resource to be used as library of applications.
CLU_STORAGE_SUBSCRIPTION_KEYS: Parameter provided by CLU to import and copy applications in CLU shared resources.

📄 For detailed information regarding how to obtain Azure credentials for CLU, please check the section Complementary processes.
📄 Information regarding how to get ABACUS variables in ABACUS documentation.
📄 If dictionaries are included in the NLP model, additional variables are required. check them in Set up specific configuration variables for dictionaries.

5.2. Execute the training script

From this point on, linguists or NLP experts have two options to continue with the process:

OPTION A	OPTION B
Use our web tool ABACUS 1.0.0. following the guidelines in ABACUS documentation. (*) After using ABACUS, continue with the process for the NLP model deployment in section Certify NLP model accuracy	Execute the training script, following the guidelines below

Execute the training script: aura-nlpdata-[country_code]/tools/build_local.sh
The script automatically creates a Python virtual environment to ensure the training and evaluation processes are being carried out in an isolated and encapsulated way.
All dependencies included in requirements.txt are installed in the virtual environment.
This script also validates the format of the involved files to ensure they match the specifications.
Once this script is executed, a tmp folder is created in the root repository. In this folder, you can find some temporary files corresponding to the resources, as well as the results and metrics obtained from the training process.
This directory is ignored by the git version control system because it has been included in the .gitignore file and it must not be included manually.

Intelligent training

The NLP system is trained in an intelligent way, so that the training of certain stages can be skipped, if they were previously trained, making the process more agile and efficient. This feature is based on the verification of an internal hash table and hash index generated after training.

The default behavior of the intelligent training is:

On one hand, only the stages that have been modified from a previous retraining in a specific channel are trained again. For this purpose, the system keeps a hash table in the tmp/ folder to detect changes.
On the other hand, if the configuration and the model generated to train a stage are the same as those of a previous stage but of a different channel, the last do not need to be trained and it will use the model trained before, making the process much more efficient. To achieve this, an internal hash index is generated in the tmp/trained_models folder. It is important that the training files in every channel are exactly the same, with similar name and similar content.

However, the hash table and hash index can be managed manually in order to modify this behavior:

Management of the hash index to force the training of a stage in a specific channel

The hash table is included in the tmp/ folder after training. This folder must not be deleted when tests are executed, unless all the stages are to be re-trained again. If you want to force the training of a specific stage, its corresponding file can be deleted in the specific channel. For instance, if there are no modifications on a stage within the mh channel, but you want to force its retraining, then go to the tmp/ folder and delete the file saved_training_hashes.json in the path:
tmp/recognizer/ob/ES/es-es/mh/resources/saved_training_hashes.json

Management of the hash index to force the training of a stage in different channels

The hash index identifies similar training files from stages of the same type that belong to different channels. It is included in the following folder: tmp/trained_models/[stage]/[hash]/

[stage]: name of a stage.
[hash]: it is resulting from the content of the training files used for that stage and its specific configuration.

Each sub-tree contains the necessary files that were used during the training phase for that specific stage.
By default, if the same stage with the same training files exists in different channels, only the first one found is retrained.
If you want to force the training for a specific stage, in addition to eliminating the hash tables seen in the previous section, delete the tmp/trained_models/[stage] for this stage.

5.3. Generation of results from the training process

When the training process is finished, certain temporary files are created in the tmp/ directory in the root repository.
This folder contains the resources of the NLP model and results and metrics from the training process obtained from launching the testing batch against the training model.

Files generated in the tmp/ directory are organized as shown in the following tables:

Input resources for the NLP model

The input resources for the NLP training are placed on:

Input resources	tmp/ folder
Training and test set files in data/	tmp/[stage]/ob/[country_code]/[language]/[channel]/
E2E test files	tmp/pipeline_eval/ob/[country_code]/resources/[language]/[channel]/
`bootstrap.cfg` config file	tmp/pipeline_eval/ob/[country_code]/etc/

Results from the NLP training

Results from the NLP training	tmp/ folder
Result files from each NLP stage training	tmp/results/[stages]/[country_code]/[language]/[channel]/
Result files from the overall pipeline training	tmp/results/pipeline_eval/[country_code]/
Result files from the overall pipeline training: regression tests	tmp/results/pipeline_eval/[country_code]/regression/

Testset files

If you have defined stage-specific E2E testset files, then after the execution of the script build_local_testset.sh, some temporary files are created in the tmp_testsets/ folder:

Testset files	tmp/ folder
Stage-specific E2E testset files	tmp_testsets/[platform]/resources/[language]/[channel]/

Each channel folder contains the end-to-end test files for each stage (currently, only for OpenAI embeddings recognizer). These files are used for the evaluation of the pipeline in future trainings and can be extended with as many tests as desired.

Intelligent training behavior

Intelligent training behavior	tmp/ folder
Hash table including the modified training files	tmp/recognizer/ob/ES/es-es/mh/resources/saved_training_hashes.json
Hash index including the modified training and test set files for a specific stage	tmp/trained_models/[stage]/[hash]/

6. Evaluate E2E accuracy locally

With all the results from the training process, saved in the tmp/results/ folders as explained before, now these results must be analyzed in order to evaluate if the NLP process is accurate enough for the recognition of intents and entities.

✅ If the local analysis of results is satisfactory at this stage, linguists can proceed to create the Pull Request.

⛔ If the analysis shows that the metrics are not good enough, meaning that the recognition is less accurate than required, then linguists must work again on the resources data to increase the performance and repeat the training process to re-calculate the metrics.

The analysis of results can be carried out from two different points of view, as explained in the following sections:

Focusing on each stage composing the pipeline
Or treating the pipeline as a single component to measure the end-to-end performance.

6.1. Evaluate NLP stages accuracy

For this purpose, analyze the following file, generated after training in the tmp/results/ folder:

tmp/results/[stages]/[country_code]/[language]/[channel]/test_results.txt

This file is generated per each pipeline stage, country, language and channel in the above-mentioned path and contains the metrics of the stage performance:

Precision: reflects false positives (false statements recognition)
Recall: reflects false negatives (missed items)
F1-score: combines precision and recall
Generation of average values

However, these metrics depend on the specific stages of the pipeline as, for example, the normalizer stage requires no evaluation and others such as Domain Classifier, NER or the intent recognizers can use all or some specific metrics among the four previously defined.

Moreover, depending on the stage, it is possible to find other files such as:

cv_results.txt that includes metrics regarding cross-validation
fitted-params.txt with information about the algorithm and parameters used to train the model.

Below, an example of test_results.txt file is shown, that corresponds to the Domain Classifier stage evaluation. The values for precision, recall, f1-score and support for each domain classified are calculated, as well as the total average.

	precision	recall	f1-score	support
None	0.40	0.84	0.54	32
intent.tv.search	0.97	0.89	0.93	122
intent.common.greetings	0.99	0.99	0.99	715
intent.billing.check	1.00	1.00	1.00	53
avg / total	0.84	0.93	0.86	922

6.2. Evaluate the overall pipeline accuracy

For the evaluation of the accuracy of the complete pipeline, you should analyze the files generated in the tmp/results/ folder after training:

tmp/results/pipeline_eval/[country_code]/
tmp/results/pipeline_eval/[country_code]/regression/

In both folders, the files are shown below, both generated from launching the testset files testset.json and regression.json:
- results.json
- details_[language]_[channel].csv
- test_results_by_intent_[language]_[channel].json
- test_results_by_intent_[language]_[channel].txt
- test_results_by_entity_[language]_[channel].json
- test_results_by_entity_[language]_[channel].txt

At this point, you are expected to analyse the results of the metrics included in these files in terms of accuracy and precision of intents and entities recognition. The files provide a detailed description about the testing statements that have obtained an unexpected result, as well as useful information for debugging purposes.

⚠️ If you use ABACUS, take into account that, currently, the tool only shows two test files: results.json and details_[language]_[channel].csv

results.json

General file that includes the results of the overall pipeline performance through statistics regarding the number of entries misclassified in the test set and their relative scores.

The metrics that contain this file are defined below:

Accuracy intent: Percentage of successful intents.
Accuracy overall: Percentage of successful inputs.
Accuracy perfect in options: Percentage of successful inputs included when the first option is right.
Entity error: Number of inputs in which entity recognition has failed.
Intent error: Number of inputs in which intent recognition has failed.
Option error: Number of inputs in which options recognition has failed.
Missing entities overall: Ratio of training statements (sentences, phrases or isolated words) in which entity recognition is failed to the total number of statements.
Missing entities right intent: Ratio of training statements in which entity recognition is failed but intent recognition is successful to the total number of statements with the intent recognized.
Missing options overall: Ratio of training statements in which options recognition is failed to the total number of statements.
Missing options right intent: Ratio of training statements in which options recognition is failed but intent recognition is successful to the total number of statements with option recognized.
Perfect: Total number of inputs without errors.
Perfect in options: Total number of inputs without errors where the first option is right.
Test size: Total number of inputs in test set file.

Additionally, each time a Pull Request (PR) is generated, a comment appears automatically in the results.json content in the GitHub repository to ease the reviewing task.

An example of the results.json file is included below:

{
    "date": "2021-08-30T09:27:03Z",
    "language": {
        "es-es": {
            "mp": {
                "accuracy_intent": 0.9681528662420382,
                "accuracy_overall": 0.9585987261146497,
                "accuracy_perfect_in_options": 0,
                "entity_error": 3,
                "intent_error": 10,
                "missing_entities_overall": 0.009554140127388535,
                "missing_entities_right_intent": 0.009868421052631578,
                "missing_options_overall": 0,
                "missing_options_right_intent": 0,
                "option_error": 0,
                "perfect": 301,
                "perfect_in_options": 0,
                "test_size": 314
           }
        }
    },
    "ob": "ES"
}

details_[language]_[channel].csv

One file is generated per each pair language/channel, containing the original training statement, the expected values versus the obtained values for intents, entities and domains after the pipeline execution as well as an additional column with a tag summarizing the error type, with five possible values:

D: error when recognizing the domain.
I: error when recognizing the intent.
E: error when recognizing the entity.
O: error when recognizing the options.
W: special tag used when result expected is the first option in recognized result.

This additional column is able to have more than one of these values. In detail, fields contained in the .csv file are:

phrase: Original statement (sentence, phrase, or isolated word) evaluated.
different: Summary of errors. It could have from one to three letters depending on the errors found. Suitable letters are D (domain), E (entities), and I (intent).
intent_obtained: Intent obtained by the pipeline.
intent_expected: Intent expected as defined in the test set.
entities_obtained: Entities obtained by the pipeline.
entities_expected: Entities expected as defined in the test set.
options_obtained: Options obtained by the pipeline.
options_expected: Options expected as defined in the test set.
domain_obtained: Domain obtained by the pipeline.
domain_expected: Domain expected as defined in the test set.

An example is shown below:

phrase	different	intent_obtained	intent_expected	entities_obtained	entities_expected	domain_obtained	domain_expected	options_obtained	options_expected

test_results by intent and by channel

They are both .txt and .json files containing the results of the pipeline performance per each pair language/channel and per intent, with the following format:

test_results_by_intent_[language]_[channel].json

The metrics that contain this file are defined below:

n: Number of successful statements.
total: Total number of statements by intent.
overall: Total accuracy by intent.
intent: Accuracy of intents by intent.
entities: Accuracy of entities by intent.
options: Accuracy of options by intent.
domain: Accuracy of domains by intent.
perfect_in_options: Number of successful statements recognized in the first option by intent.

Example of test_results_by_intent_[language]_[channel].json:

  "intent.common.greetings": {
    "n": 2,
    "total": 2,
    "overall": 1.0,
    "intent": 1.0,
    "entities": 1.0,
    "options": 1.0,
    "domain": 1.0,
    "perfect_in_options": 0.0
  }
}

test_results_by_intent_[language]_[channel].txt

Same fields as the JSON file but written in legible mode.

Example of test_results_by_intent_[language]_[channel].txt:

PIPELINE RESULTS: 
      intent.common.greetings: n:2, Total: 2, Accuracy (Overall): 1.000000, Accuracy (Intent): 1.000000, Accuracy (Entities): 1.000000, Accuracy (Options): 1.000000, Accuracy (Domain): 1.000000, Accuracy (Perfect in options): 0.000000
------------------------------

      Test Size: 4

test_results by entity and by channel

They are both .txt and .json files containing the results of the pipeline performance per each pair language/channel and per entity, with the following format:

test_results_by_entity_[language]_[channel].json

The metrics that contain this file are defined below:

n: Number of successful statements.
total: Total number of statements by entity.
overall: Total accuracy by entity.
intent: Accuracy of intents by entity.
entities: Accuracy of entities by entity.
options: Accuracy of options by entity.
domain: Accuracy of domains by entity.
perfect_in_options: Number of successful statements recognized in the first option by entity.

An example is shown below:

{ 
  "ent.audiovisual_film_title": { 
    "n": 4, 
    "total": 4, 
    "overall": 1.0, 
    "intent": 1.0, 
    "entities": 1.0, 
    "options": 1.0, 
    "domain": 1.0 
  } 
}

test_results_by_entity_[language]_[channel].txt

Same fields as the .json file but written in legible mode.

Example:

PIPELINE RESULTS BY ENTITIES: 
------------------------------
           ent.audiovisual_film_title: n:4, Total: 4, Accuracy (Overall): 1.000000, Accuracy (Intent): 1.000000, Accuracy (Entities): 1.000000, Accuracy (Options): 1.000000, Accuracy (Domain): 1.000000
------------------------------

      Total uniques Entities: 1

      Total Entities: 4

6.3. Analyze compatibility between global grammars and local grammars

⚠️ The current section only applies if both global and local grammars are implemented in the NLP recognition process.

As explained in Grammars management the two types of grammars defined in Aura NLP recognition process, global and local, must be aligned. For checking the compatibility between both grammars, you must generate two test set files:

data/[language]/[channel]/test_grammar/commons/testset.json
Test set with statements that must be recognized by both grammars (with identical results).
data/[language]/[channel]/test_grammar/disjoints/testset.json
Test set with statements that must be only recognized by the global grammar (as the local grammar is a subset of the global grammar).

Both tests are JSON files including a list of test phrases, as shown in the example:

[
  "push play again",
  "turn on the light"
]

These tests run through an automatic process and, if some error is detected, it is reported. In this scenario, linguists must check the errors and fix them:

Errors in disjoints testset

Local grammar recognizes a global phrase
This error occurs when a disjoint testset statement is recognized by the local grammar. An example of this error message for the language es-es, channel mh and the statement “push play again”:
```
Local grammar recognized a global phrase "push play again" for language es-es and channel mh
```
To resolve this problem, carry out the required modifications over the local grammar in order not to recognize the statement.
Global grammar does not recognize a test statement
This error occurs when a disjoint test set statement is not recognized by the global grammar.
```
Error recognizing phrase: " push play again " by pipeline grammar for language es-es and channel mh
```
To resolve this problem, carry out the required modifications over the global grammar in order to recognize the statement.

Errors in the commons testset

Local grammar does not recognize the statement but global grammar does. The program logs the following error message:
```
Error recognizing phrase: "turn on the light" by local grammar for language es-es and channel mh
```
In order to fix this error, improve the local grammar.
Global and local grammars recognize different intents The program logs the following error message:
```
Recognized phrase "turn on the" by both grammar with different intents.
Pipeline intent: intent.domotics.light_off, 
Local grammar intent: intent.domotics.light_on
```
In order to fix this error, improve both grammars to make them recognize the same intents.
Global grammar does not recognize the statement but local grammar does The program logs the following error message:
```
Error recognizing phrase: "turn on the light" by pipeline grammar for language es-es and channel mh
```
In order to fix this error, improve the global grammar.

6.4. Launch and test your pipeline locally (live mode)

Another useful functionality for a quick a real-time evaluation of the accuracy of the NLP model is running the pipeline in live mode in local environment.

To use this interactive execution approach:

Execute the script:
aura-nlpdata-[country_code]/tools/run_local_pipeline.sh
Once the script is run, select manually both channel and language.
After that, insert testing statements representing potential users’ utterances through the command line in a responsive way.
Evaluate the response in real time to the input statement: the associated intents, entities and score provided by the system.

⚠️ It is important to run this script after the build_local.sh (that is, after training the model) to ensure the system has been trained and all the resources have been generated.

This script neither generates temporary files nor directories and it can be run from the IDE or the OS terminal.

7. Pull Request to release branch

All the steps in previous sections are developed in a local branch, cloning the NLP master branch.

Once the NLP model is validated locally, now you must create a Pull Request (PR) to your release branch in order to upload your files and apply for validation to the NLP Global Team.

Follow the steps explained hereunder to create a Pull Request in the GitHub web application:

Verify current working branch and files to be included in the Pull Request: git status
If, when executing this command, there are files that should not be uploaded, remove them using git checkout and the path of the corresponding file that appears in status.
Add the local files: git add <file_name>

Use git add -A to upload all files in your local branch.
Use git rm <file1> <file2> <file3> if you need to remove certain modified files.

Commit changes with the command git commit -a "[[<feat>]] change description"
Execute the command git pull as an optional step to check if, during the execution of these commands, there are modifications in the same path that can produce further errors.
Push local branch: git push origin <branch_name>
Create a Pull Request to release branch: Access to the corresponding directory: aura-nlpdata-[country_code]/
And create a Pull Request from this branch to master or to the current release branch.
The title of the PR should start with [[feat]], [[fix]], or [[release]] and contain a representative description of the modifications.

Access our best practices for the creation of a Pull Request.

8. Certify NLP model accuracy

⚠️ REMEMBER… If you have used the tool ABACUS for the local training, testing and publication of your NLP model, now you must continue here with the process for its deployment.

When the Pull Request is launched, a validation process starts for the evaluation of the NLP recognition process: the so-named Continuous Integration (CI), defined as a process for the integration of code into a shared repository and its validation.
The validation comprises the execution of the training script build_local.sh by the NLP Global Team, that launches two processes:

An automatic validation process.
A manual review of results by the NLP Global Team.

Automatic generation of the NLP metrics

The system automatically generates certain metrics files for checking:

Accuracy of the whole pipeline
Accuracy of specific intents
Ratio of test set
Valid format of files
Modification without permission or by mistake of certain tasks
Compatibility between local and global grammars

These metrics will be included in the PR conversation using the E2E files testest.json and regression.json in order to provide a summary of the NLP system quality.

Review by the NLP Global Team

Complementary, the NLP Global Team carries out a review of results and report the existing problems.

The setting of an adequate threshold for the NLP system accuracy depends on the use case. Therefore, for a specific use case, the minimum accuracy should be agreed by L-CDO and the NLP Global Team.

After the Pull Request approval by Aura Global Team, the modifications are ready to be merged.

It can be very useful for Local Teams to know the process and criteria used by the NLP Global Team to validate the NLP model in order to focus on the critical points. Discover all this information in Validation process by the NLP Global Team.

9. Merge and generate your understanding package

At this stage, after the Pull Request approval, you are ready to merge the Pull Request in GitHub. Modifications are then included in the NLP release branch.

The system automatically initiates the process for the generation of the new version of the understanding package (artifact): a new Debian package with the version and name of the corresponding Platform release. This process can last a few hours.

When the new understanding package is generated, an e-mail is sent to PMOs, communicating that there is a new version available.

The APE Team is in charge of communicating the OB the name of the new package.

Now, the Local DevOps Team is responsible of the deployment of the understanding package.

10. Deploy the new understanding package

Once the previous stages are completed, the Local DevOps Team should deploy the NLP artifact with the new or updated trainings.

Remember that OBs are able to deploy NLP packages through a hot swapping process.

📄 For both processes, the local DevOps Team should check the document Aura Deployment of NLP packages.

Docs:

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

Use Aura global experiences

Learn how to make the most of Aura global use cases, experiences already developed by Aura Platform Team at your disposal

Introduction

In this section, two actions to be done over Aura global use cases are explained, both for the edition of texts in Aura response and for analyzing how the experience has been developed.

Build Aura response: edit POEditor texts

ℹ️ This section is intended for OBs’ content managers in charge of editing texts included in Aura response.

When a global use case is implemented, it is necessary to design Aura response for each step of the conversational flow. The different texts, in a specific language, shown to the user are designed through POEditor.

For global use cases, you should work over the POEditor Aura-bot project, which is managed by the Aura Platform Team.
Resources are already created in aura-bot, so at this stage you only have to edit the copies (texts) of each resource.

Edit texts

In the POEditor global project, edit the texts (copies) of the existing resources associated with the use case under development or translate texts to one specific language.

Follow the Guidelines for the edition of texts in POEditor but taking into account that you have to work with Aura Global project in POEditor.

Import locale files

Import the locales files from POEditor to aura-bot.

Once imported, when a new version of the library is generated, they are automatically integrated during the make-up process.

Management of locales for intents canonical phrases

The management of canonical phrases for intents has been implemented in POEditor, as intents must have a canonical phrase to be able to disambiguate with them.

To do this, follow the guidelines in Manage locales for canonical phrases of intents.

Analyze a global use case in local environment

Moreover, OB product managers can be interested in analysing the global use cases in order to know how they are designed, their structure and files, associated dialog logic, etc. This can be an inspiration for building your own local experiences.

From the point of view of aura-bot, the OB should carry out the following tasks:

Get started and configure Aura Bot

This step is required only for developers that firstly face aura-bot and need the creation and configuration of a bot service in your local environment.

If this is your case, learn how to do it the section Get started with Aura Bot.

Install global use cases dependencies in local environment

In order to install the versions needed, update the file local-dependencies/libraries-list.json and set the corresponding versions of your libraries. Remember to add a new profile if checking a new version of the libraries.

The installation of the libraries must be carried out through the following command: npm run local-dependencies:install This command adds the dependencies of the global use case libraries both in package.json and plugin-config.json files and installs them into the project.
To uninstall libraries from global use cases, developers must use the following command: npm run local-dependencies:uninstall This command uninstalls all the dependencies of the global libraries previously installed, and also clears the file package.json and plugin-config.json.

Bot running

Once the aura-bot instance is properly configured according to the guidelines established in the previous sections, the instance can be started using the following command for running the bot in local environment:
npm start

The previous command can be enriched passing environment variables following the guidelines stated by the concrete operating system where the aura-bot instance is about to be started.

Docs:

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

Narugo normalization pipeline

Description and stages

Narugo is a pipeline used for the normalization of the user’s utterance through the execution of the following normalizers:

PunctuationNormalizer
SplitPunctNormalizer
SpaceNormalizer
CurrencyNormalizer
UnicodeNormalizer
LowercaseNormalizer
CardinalityNormalizer

Configuration

This stage requires the following configuration in the nlp.json configuration file:

{
  "es-es": {
    "mp": {
         "nlp": {
         "normalizer_pipeline_class": "auracog_pipelines.pipelines.normalization.narugo.NarugoPipeline"
      }
    }
  }
}

Docs:

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

Catalog of NLP connectors

NLP connectors to compose the NLP pipeline

Aura Platform Team has implemented different types connectors to join NLP stages in order to configure the pipeline.

Select your intended connector in the left menu. Each of them is characterized by its description, path, files and configuration.

Section	Content	Role in the NLP process
Description	Identification and objective of the stage in the recognition process	Descriptive purpose of the stage in the recognition process
Path	Class path (Python class) of an element (stage or connector)	The path of each stage of the pipeline must be included in the file `pipeline.json` for building up the NLP dynamic pipeline
File	Specific training files and test set files for the NLP stage required to train and validate the NLP model	Linguists must generate these files for the training and the validation of the NLP model during the data resources definition
Configuration	Required configuration for each NLP stage	Configuration of each stage of the NLP model

Docs:

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

Aura NLP normalizers

What are Aura NLP normalizers

Text normalization is the process of transforming an Aura user’s utterance (expressed in natural language) into a standardized one to be more easily recognized by Aura NLP.

During the normalization process, certain characters are replaced/removed in order to reduce the input diversity that does not provide relevant information to Aura, such as replacing uppercase by lowercase letters, removal of punctuation marks, etc.

Within Aura NLP, there are different normalization stages which are handled as simple stages, taking part of a pipeline. Additionally, it is possible to define pipelines composed only by normalization stages suitable to be nested into another pipeline.

The following sections show the Aura NLP normalizers included in the current catalog.

Cardinality

The cardinality normalizer replaces ordinal or cardinal numbers expressed in text characters by digits. It cannot be used for percentages. For this purpose, the normalizer uses a fork of the library Microsoft.Recognizers.Text.

Example: “Put the second $” –> “Put the 2$”; “$Give me ten results” –> “$ Give me 10 results”.

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.cardinality_normalizer_wrapper.CardinalityNormalizerWrapper

Currency

This normalizer provides an appropriate format to the amount and currency in an utterance, separating the currency symbol from the amount with a single space. The implementation of this normalizer can be consulted in https://github.com/Telefonica/Recognizers-Text.

It is able to read the following currencies: $, € and £.

Example: “1$” –> “1 $”; “$1” –> “$ 1”; “1€” –> “1 €”.

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.currency_normalizer_wrapper.CurrencyNormalizerWrapper

FromConfig

FromConfig normalizer executes the normalization pipeline defined in configuration.

This normalizer does not require any file.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.from_config_normalizer_wrapper.FromConfigNormalizerWrapper

Configuration

This stage requires the following configuration in the nlp.json file.

  "es-es": {
    "mp": {
      "nlp": {
        "normalizer_pipeline_class": "auracog_pipelines.pipelines.normalization.nabro.NabroPipeline",
      }
  }
}

Where:

normalizer_pipeline_class: in this field, the specific normalization pipeline is referred (Nabro, Narugo, Nikko or Noro).

Lowercase

The lowercase normalizer replaces uppercase characters by lowercase ones in the utterance.

Example: “watch the NBA” –> “watch the nba”.

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.lowercase_normalizer_wrapper.LowercaseNormalizerWrapper

Punctuation

The punctuation normalizer removes special punctuation characters (¿?¡!,.;:) from the utterance, inserting blank spaces instead.

Example: “How are you? Fine, thanks!” –> “How are you Fine thanks”.

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.punctuation_normalizer_wrapper.PunctuationNormalizerWrapper

Space

The Space normalizer removes duplicated spaces from the utterance reducing space sequences to a single space.

Example: “How are you Fine” –> “How are you Fine”

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.space_normalizer_wrapper.SpaceNormalizerWrapper

Split Punct

Split Punct normalizer tokenizes the utterance splitting by words and punctuation marks using the NLTK framework. This framework uses NLTK recommended word tokenizer (currently an improved TreebankWordTokenizer that uses regular expressions to tokenize the text, together with PunktSentenceTokenizer that builds a model for abbreviations, collocations and words starting sentences.

The model is used to find sentence boundaries. The result is the utterance split by words separated by single spaces.

Example: “Please!!, get out now… right?” –> “Please ! ! , get out now … right ?”.

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.split_punct_normalizer_wrapper.SplitPunctNormalizerWrapper

Stop words

The stop words normalizer removes stop words, defined as commonly used words such as “the”, “is”, “at”, “which”, or “on” from the user’s utterance. This normalizer is able to recognize stop words from different languages using the NLTK framework.

Example: “its ok, I prefer the first or second option too” –> “ok prefer first second option”

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.stop_words_normalizer_wrapper.StopWordsNormalizerWrapper

Unicode

The Unicode normalizer replaces non-Unicode characters by other characters pre-defined in the Unicode characters list.

Example: “the 1º stop will be in München” –> “the 1. stop will be in munchen”.

This normalizer does not require any file or configuration.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.unicode_normalizer_wrapper.UnicodeNormalizerWrapper

Stop words from file

While the previous normalizer identifies predefined stop words from a database, the current normalizer allows the generation of a customized list of stop words, leading to a more accurate recognition of the user’s utterance.

The stop words from file normalizer requires the edition of the stop_words.json file to define a list of personalized stop words for each language and channel. This file must be placed at:
aura-nlpdata-[country_code]/data/[language]/[channel]/stop_words.json

The stop_words.json file performs the following tasks during the training process:
- Transforms each word to lowercase
- Removes repeated words

This normalized file is saved in a new file normalized_stop_words.json, in a temporary directory.

When Aura receives a request from the user, the behavior of the stop words from file normalizer is shown below for a specific example:

File content of stop_words.json: [“Its”, “its”, “I”, “,”, “the”, “or”, “which”]
Utterance: “its ok, I prefer the first or second option too” –> “ok prefer first second option too”

⚠️ When this normalizer is used, the words to be included in the stop_words.json file must be already normalized.

⚠️ The normalization does not validate if the defined “stop word” in the file is composed by only one word. Therefore, a “stop word” could be composed by more than one word.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.stop_words_from_file_normalizer_wrapper.StopWordsFromFileNormalizerWrapper

Word replacer from file

The Word replacer from file normalizer allows the exchange of words in the utterance.

The word replacer from file normalizer requires the edition of the word_replacer_mapper.json file to define a mapper containing the final words as a key and the list of words to replace as a value for each language and channel. This file must be placed at:
aura-nlpdata-[country_code]/data/[language]/[channel]/word_replacer_mapper.json

The word_replacer_mapper.json file performs the following tasks during the training process:
- Transforms each word to lowercase
- Removes repeated words in word values

This normalized file is saved in a new file normalized_word_replacer_mapper.json, in a temporary directory.

When Aura receives a request from the user, the behavior of the word replacer from file normalizer is shown below for a specific example:

File content of word_replacer_mapper.json:

{
  "hello": ["hi", "greetings", "howdy", "hey"],
  "option": [ "alternative"]
}

Utterance: “howdy, i want the second alternative” –> “hello, i want the second option”

⚠️ When this normalizer is used, the words to be included in the word_replacer_mapper.json file must be already normalized.

⚠️ All values should be only composed by one word. If a value contains more than one word, the normalizer raises an error in the training process. If multiple words are allowed, the normalization process is not idempotent.

Path

auracog_pipelines.stage_wrappers.normalizer_wrapper.word_replacer_from_file_normalizer_wrapper.WordReplacerFromFileNormalizerWrapper

Docs:

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

Recognition of utterances with several entities in Grammars

Specific guidelines in the scenario when the user’s utterance includes several entities to be recognized by Grammars through the use of roles

Use of roles for the recognition of utterances with several entities

If the user’s utterance contains several entities of the same type, it is required to add a role tag to the entity identifier, following the format: [entity_name:rol_value]
The role tag is used by the system to identify that there are two entities of the same type but with different roles.

This process will not affect the final output of the Grammars. That is, if the entity with the role is ent.audiovisual_sports_team:visitor, the system will only retrieve the tag ent.audiovisual_sports_team.

A practical example of Grammars that use this functionality is shown below:

The utterance “I would like to see Madrid against Barsa” contains two entities of the same type: [ent.audiovisual_sports_team]
For both entities to be detected correctly, it will be necessary to add the role when defining the name of the entities. For example, the roles of local and visitor could be assigned, resulting [ent.audiovisual_sports_team:local] and [ent.audiovisual_sports_team:visitor]

Certain considerations must be considered:

In order to recognize two entities of the same type in sequence, there is no need to create two entity graphs with the role tag but one, since the system is capable of discerning between the tagged entity and the untagged one.
Entity values should be the same in both graphs.
For better understanding purposes, we suggest using digits to name the entity graph having the role with the name of the role itself. For example: ent.audiovisual_sports_team:1 -> ent.audiovisual_sports_team_1.grf
This can be also done using non-digit characters. That is, if the entity ent.audiovisual_sports_team has the role “visitor” (ent.audiovisual_sports_team:visitor), the name of the graph should be ent.audiovisual_sports_team_visitor.grf.

Docs:

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

Rendering Aura response components in WhatsApp

Rendering capabilities of WhatsApp channels for every component of Aura response

Introduction

The current document identifies, for every component of Aura response, how aura-bridge converts it to be shown in WhatsApp and the limitations and constraints for this channel.

⚠️ Make sure the channel you are working with is not configured to force a particular list type. Otherwise, you may get unwanted results.
You can find this option in the WhatsApp model, which is part of Aura channel model.
Please go to the aura-configuration-api for further information regarding how to check the current configuration for the channels.

Texts

Users’ utterance

The user’s utterance is not an element to be included in Aura response but, likewise, the channel must render it.

ID	Description	JSON response
text.utterance.01	The user inserts a basic sentence	“What data plan do you recommend me?”
text.utterance.03	The user inserts a long request	“Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat”
text.utterance.04	The user inserts a request with a line break	“Dear Aura, How can I upgrade my bundle?”
text.utterance.05	The user inserts a request including hyperlinks	“Can you explain me this offer? https://www.movistar.es/particulares/fusion/inicia-600Mb?pid=clic-boton-meinteresa-corner-movistar-imagenio"
text.utterance.06	The user inserts a request including emojis	“Hi 😊”

Insight

ID	description	JSON components	Command
text.insight.01	Generation of an insight including all the markdown allowed options	Insight 01 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.01"}]}`
text.insight.02	Generation of an insight with one URL and an image in the preview	Insight 02 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.02"}]}`
text.insight.03	Generation of an insight including one URL with no image in the preview	Insight 03 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.03"}]}`
text.insight.04	Generation of an insight including URLs with markdown	Insight 04 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.04"}]}`
text.insight.05	Generation of an insight text with blank text	Insight 05 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.05"}]}`
text.insight.06	Generation of an insight including long text	Insight 06 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.06"}]}`
text.insight.07	Generation of an insight with very long words	Insight 07 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.07"}]}`
text.insight.08	Generation of an insight with long text (more than 4096 characters)	Insight 08 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.08"}]}`
text.insight.09	Generation of an insight with simple text	Insight 09 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.09"}]}`
text.insight.10	Generation of an insight including text with a URL and an image in the preview	Insight 10 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.10"}]}`
text.insight.11	Generation of an insight including text with a URL and with no image in the preview	Insight 11 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.11"}]}`
text.insight.12	Generation of an insight with two URLs	Insight 12 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.12"}]}`
text.insight.13	Generation of an insight with specific characters used in different use cases in OBS	Insight 13 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.13"}]}`
text.insight.14	Generation of an insight including a text and a YouTube or Vimeo URL	Insight 14 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.14"}]}`
text.insight.15	Generation of an insight with a list-format text	Insight 15 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"insight","entity":"text.insight.15"}]}`

Cards

Adaptive Cards

WhatsApp channel is not able to render Adaptive Cards.

Hero Cards

ID	description	JSON components	Command
card.hero.01	Hero card including tittle, sub-tittle and image	Hero Card 01 JSON file	`{"intent":"intent.factotum-test.hero-card-01"}`
card.hero.02	Hero card including tittle, sub-tittle, image and URL	Hero Card 02 JSON file	`{"intent":"intent.factotum-test.hero-card-02"}`
card.hero.03	Hero card including tittle, image and URL	Hero Card 03 JSON file	`{"intent":"intent.factotum-test.hero-card-03"}`
card.hero.04	Hero card including title, subtitle and URL (without text)	Hero Card 04 JSON file	`{"intent":"intent.factotum-test.hero-card-04"}`
card.hero.05	Hero card including title, subtitle and URL	Hero Card 05 JSON file	`{"intent":"intent.factotum-test.hero-card-05"}`
card.hero.06	Hero card including title	Hero Card 06 JSON file	`{"intent":"intent.factotum-test.hero-card-06"}`
card.hero.07	Hero card with text containing a URL	Hero Card 07 JSON file	`{"intent":"intent.factotum-test.hero-card-07"}`
card.hero.08	Hero card with image	Hero Card 08 JSON file	`{"intent":"intent.factotum-test.hero-card-08"}`
card.hero.09	Hero card with an image in format different from jpeg and png	Hero Card 09 JSON file	`{"intent":"intent.factotum-test.hero-card-09"}`
card.hero.10	Hero card including an empty list of images	Hero Card 10 JSON file	`{"intent":"intent.factotum-test.hero-card-10"}`
card.hero.11	Hero card including a list of images with wrong URLs	Hero Card 11 JSON file	`{"intent":"intent.factotum-test.hero-card-11"}`
card.hero.12	Hero card with a list of images	Hero Card 2 JSON file	`{"intent":"intent.factotum-test.hero-card-12"}`
card.hero.13	3 Hero cards (array of cards)	Hero Card 13 JSON file	`{"intent":"intent.factotum-test.hero-card-13"}`
card.hero.14	Hero card with title and URL	Hero Card 14 JSON file	`{"intent":"intent.factotum-test.hero-card-14"}`
card.hero.15	Hero card with title, subtitle and text	Hero Card 15 JSON file	`{"intent":"intent.factotum-test.hero-card-15"}`
card.hero.16	Hero card with activity as text	Hero Card 16 JSON file	`{"intent":"intent.factotum-test.hero-card-16"}`
card.custom	HeroCard (suggestion) with 3 options to show reply buttons	Custom card 01 JSON file	`{"intent":"intent.factotum-test.hero-card-custom-dialog", "entities": [{"entity": "0", "type": "heroCards"}, {"entity": "3", "type": "options"}, {"entity": "20", "type": "charactersByOption"}, {"entity":"{\"type\":\"button\"}", "type":"whatsappListOptions"}]}`
card.custom	HeroCard (suggestion) with 5 options to show a WhatsApp list messages	Custom card 02 JSON file	`{"intent":"intent.factotum-test.hero-card-custom-dialog", "entities": [{"entity": "0", "type": "heroCards"}, {"entity": "5", "type": "options"}, {"entity": "20", "type": "charactersByOption"}, {"entity":"{\"type\":\"list\"}", "type":"whatsappListOptions"}]}`
card.custom	HeroCard (suggestion) with 5 options to show an enumerated text list	Custom card 03 JSON file	`{"intent":"intent.factotum-test.hero-card-custom-dialog", "entities": [{"entity": "0", "type": "heroCards"}, {"entity": "12", "type": "options"}, {"entity": "20", "type": "charactersByOption"}, {"entity":"{\"type\":\"enumeratedList\"}", "type":"whatsappListOptions"}]}`
card.custom	HeroCard with no images and suggestions with 2 reply buttons	Custom card 04 JSON file	`{"intent":"intent.factotum-test.hero-card-custom-dialog", "entities": [{"entity": "simple", "type": "profile"}, {"entity": "2", "type": "options"}, {"entity": "20", "type": "charactersByOption"}, {"entity":"{\"type\":\"button\"}", "type":"whatsappListOptions"}]}`
card.custom	2 HeroCard with images and suggestions with 5 options to show as WhatsApp list messages	Custom card 05 JSON file	`{"intent":"intent.factotum-test.hero-card-custom-dialog", "entities": [{"entity": "default", "type": "profile"}, {"entity": "5", "type": "options"}, {"entity": "20", "type": "charactersByOption"}, {"entity":"{\"type\":\"button\"}", "type":"whatsappListOptions"}]}`

Templates

ID	description	Curl/JSON
test_global_aura_plain_text_no_header	Template containing a body with an explanatory text (unique mandatory element in a template)	Template 01 Curl file Template 01 JSON file
test_global_aura_plain_text_with_header_and_deeplink	Template containing: - Header (title) - Body (explanatory text) - Deeplink button	Template 02 Curl file Template 02 JSON file
test_global_aura_header_imagen_body_quick_reply	Template containing: - Header (title) - Body (explanatory text) - Quick reply text	Template 03 Curl file
test_global_aura_account_update_body_two_buttons	Template containing: - Header including text with parameters - Body with parameters - Footers without parameters - Deeplink button - CTA (call-to-action)	Template 04 Curl file
test_global_aura_header_document_body	Template containing: - Header with a file - Body with parameters	Template 05 Curl file
test_global_aura_header_video_body_footer_tree_buttons	Template containing: - Header with a video - Body (explanatory text) - Footer - Quick reply buttons (max. 3 buttons)	Template 06 Curl file
pnuevo_ofrecimiento_sinvincular_v6	Template containing: - Body with parameters - 2 quick reply buttons	Template 05 JSON file
pnuevo_aceptacion_sinvincular_v2	Template containing: - Body with parameters - 2 quick reply buttons	Template 06 JSON file

Buttons

Suggestions

ID	Description	JSON components	Command
button.suggestion.01	Generation of basic suggestions with recommendations	Suggestion 01 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.suggestion.01"}]}`
button.suggestion.02	Generation of suggestions with texts longer than 80 characters (recommended length)	Suggestion 02 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.suggestion.02"}]}`
button.suggestion.03	More than 3 suggestions	Suggestion 03 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.suggestion.03"}]}`
button.suggestion.04	Empty suggestions	Suggestion 04 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.suggestion.04"}]}`
button.suggestion.05	Suggestions with blank text	Suggestion 05 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.suggestion.05"}]}`

Actions

ID	Description	JSON components	Command
button.Actions.01	Generation of actions (yes/no)	Actions 01 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.actions.01"}]}`
button.Actions.02	Generation of recommended basic actions	Actions 02 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.actions.02"}]}`
button.Actions.03	Generation of actions with texts longer than 70 characters (recommended length)	Actions 03 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.actions.03"}]}`
button.Actions.04	More than 3 actions	Actions 04 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.actions.04"}]}`
button.Actions.05	Empty actions	Actions 05 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.actions.05"}]}`
button.Actions.06	Actions with blank text	Actions 06 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.actions.06"}]}`

External buttons

ID	Description	JSON components	Command
button.external.01	Basic link to an external page	External button 01 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.01"}]}`
button.external.02	Link buttons with texts longer than 20 characters	External button 02 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.02"}]}`
button.external.03	More than 1 link	External button 03 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.03"}]}`
button.external.04	Blank links	External button 04 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.04"}]}`
button.external.05	Links with blank text	External button 05 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.05"}]}`
button.external.06	Blank URL	External button 06 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.06"}]}`
button.external.07	Link buttons with texts longer than 20 characters (recommended length) in markdown format	External button 07 JSON file	`{"intent":"intent.factotum-test.whatsapp-formats","entities":[{"type":"buttons","entity":"button.external.07"}]}`

Combination of elements in Aura response

ID	Description	JSON components	Command	Rendering in WhatsApp
Mix.message.01	message 1: Insight message 2: Hero card message 3: Suggestions with 1-3 options and less than 20 characters	Mix message 01 JSON files	`{"intent":"intent.factotum-test.mix-message-01"}`	According to default configuration. The use case or channel can change this configuration and use lists or numbered messages in suggestions. Remember that, currently, options in cards are not compatible with list messages or reply buttons.
Mix.message.02	message 1: Insight message 2: Herocards message 3: suggestions with 4-10 options and less than 20 characters	Mix message 02 JSON files	`{"intent":"intent.factotum-test.mix-message-02"}`	According to default configuration. The use case or channel can change this configuration and use numbered messages in suggestions. Remember that, currently, options in cards are not compatible with list messages or reply buttons.
Mix.message.03	message 1: Insight message 2: Herocards message 3: suggestions with more than 10 options and/or more than 20 characters	Mix message 03 JSON files	`{"intent":"intent.factotum-test.mix-message-03"}`	According to default configuration. Remember that, currently, options in cards are not compatible with list messages or reply buttons.
Mix.message.05	message 1: HeroCards message 2: Herocards message 3: Herocards Message 4: suggestion	Mix message 05 JSON files	`{"intent":"intent.factotum-test.mix-message-05"}`	According to default configuration, depending on the number of suggestions (options) and the character. For less than 3 options and less than 20 characters, we use reply buttons. The use case or channel can change this configuration and use lists or numbered messages in suggestions. Currently, options in cards are not compatible with list messages or reply buttons.

Restrictions in the response from WhatsApp channel

There are certain components that are not allowed by WhatsApp channel. Thus, if they are sent as part of the response, WhatsApp will show an error to the user. The error message is configurable by POEditor, as explained in the document Error management in WhatsApp channel.

Aura response component	Aura response sub-component	Behaviors not allowed by WhatsApp
Texts	Insight	Generation of an insight including blank text.
Texts	Insight	Generation of an insight with long text of more than 4096 characters.
Cards	Adaptive Cards	WhatsApp channel does not support Adaptive Cards.
Cards	Hero Cards	Hero card including an image with format different from jpeg and png.
Cards	Hero Cards	Hero card with an empty list of images.
Cards	Hero Cards	Hero card including a list of images with wrong URLs formats.

JSON components

Insights

Insight 01 JSON file

{
  "text": "I'm here to **help** you, if you want to see more _examples_ of ~~consultation~~, ```click``` the question +mark+."
}

Insight 02 JSON file

{
  "text": "https://ver.movistarplus.es"
}

Insight 03 JSON file

{
  "text": "www.movistar.es/particulares/Aura"
}

Insight 04 JSON file

{
  "text": "Aura can answers with texts that can also contain [markdown links](https://ver.movistarplus.es/)\n\nLet's [see](www.google.es) [how](www.yahoo.com) they are rendered in the different channels."
}

Insight 05 JSON file

{
  "text": "",
}

Insight 06 JSON file

{
  "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras nunc elit, auctor ut lectus vel, blandit eleifend turpis. Nam malesuada cursus arcu. Pellentesque eu magna non lectus eleifend mattis in nec libero. Quisque lacinia eget ligula aliquam accumsan. Mauris elementum, leo sed commodo convallis, risus purus mollis erat, vel tristique ex sapien nec nunc. Proin venenatis leo id enim tempus porttitor. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Ut sit amet mi sed eros molestie varius. Vivamus at purus neque. Suspendisse malesuada mi at interdum consectetur. Nulla facilisi. Curabitur eros enim, ornare in diam quis, auctor aliquet felis.\n\nPellentesque cursus sapien ut lorem vehicula vestibulum. Suspendisse convallis malesuada vehicula. Nulla ut leo sit amet risus congue facilisis ut at tellus. Quisque erat metus, consequat id leo non, vulputate auctor est. Ut nec viverra felis. Interdum et malesuada fames ac ante ipsum primis in faucibus. Vivamus leo ante, dictum vitae ornare et, mattis vitae neque. Integer sit amet auctor eros. Sed at erat mauris. Phasellus quis commodo quam. Phasellus vel mattis felis. In quis eleifend lacus. Phasellus in felis leo. Mauris ultricies nec eros eget pulvinar. Nulla pellentesque hendrerit elementum. Donec cursus scelerisque sem, at."
}

Insight 07 JSON file

{
  "text": "Loremipsumdolorsitamet, consecteturadipiscingelit. Crasnuncelit, auctorutlectusvel, blanditeleifendturpis. Nammalesuadacursusarcu. Pellentesqueeu magnanonlectuseleifendmattisinneclibero. Quisquelaciniaeget ligulaaliquamaccumsan."
}

Insight 08 JSON file

{
  "text": "...long.text"
}

Insight 09 JSON file

{
  "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios."
}

Insight 10 JSON file

{
  "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios. This test try to understand how the channel render different links included in the message. https://ver.movistarplus.es"
}

Insight 11 JSON file

{
  "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios. This test try to understand how the channel render different links included in the message. https://www.movistar.es/particulares/Aura"
}

Insight 12 JSON file

{
    "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios. This test try to understand how the channel render different links included in the message. https://www.movistar.es/particulares/Aura, La nueva URL seria esta http://ver.movistarplus.es/"
 }

Insight 13 JSON file

{
  "text": "Sample response including order characters:\n\n• Service-Hotline [0176 888 55 282](tel:+4917688855282). Talk on the phone!.\n\n• Talk with our online chat [Live-Chat](https://g.o2.de/aura-chat-service)\n\n• Send us an email to [our email](mailto:pallete@telefonica.es)"
}

Insight 14 JSON file

{
   "text": "This is a bodycopy to test different scenarios and the channel behaviour for this scenarios. This test try to understand how the channel render different links included in the message. https://youtu.be/7RHRRdaqExY"
 }

Insight 15 JSON file

{
  "text": "Actions that Aura can do for you:\n\n**1.**\t One choice type string\r\n**2.**\t One choice type Choice\r\n**3.**\t Two text messages\n**4.**\t HeroCard\n**5.**\t AdaptiveCard\n**6.**\t Suggestions"  
}

Hero Cards

Hero Card 01 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "**iPhone 7 Apple iPhone**",
            "subtitle": "**Price:**",
            "text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product",
            "images": [
              {
                "url": "iphone_red.png"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
 }

Hero Card 02 JSON file

 {
   "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "**iPhone 7 Apple iPhone**",
            "subtitle": "**Price**:",
            "text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product",
            "images": [
              {
                "url": "https://jira.tid.es/secure/attachment/1778109/Group%2043%403x.png"
              }
            ],
            "buttons": [
              {
                "type": "openUrl",
                "value": "https://www.movistar.es/",
                "title": "Check Movistar app for more details"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 03 JSON file

 {
   "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "**iPhone 7 Apple iPhone**",
            "text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product",
            "images": [
              {
                "url": "https://jira.tid.es/secure/attachment/1778109/Group%2043%403x.png"
              }
            ],
            "buttons": [
              {
                "type": "openUrl",
                "value": "https://www.movistar.es/",
                "title": "Check Movistar app for more details"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 04 JSON file

 {
   "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "_Fusion Plan_",
            "subtitle": "**Activated on the 12/11/2020**",
            "buttons": [
              {
                "type": "openUrl",
                "value": "https://www.movistar.es/bundle_details.html",
                "title": "Check Movistar app for more details"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 05 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "_Fusion Plan_",
            "subtitle": "**Activated on the 12/11/2020**:",
            "text": "**$35,00 Monthly fee**\n**$25,00 Comsumption**\n**$5,00 Taxes",
            "buttons": [
              {
                "type": "openUrl",
                "value": "https://www.movistar.es/bundle_details.html",
                "title": "Check Movistar app for more details"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 06 JSON file

{
  "card": {
   "hero": {
     "type": "message",
     "attachmentLayout": "list",
"attachments": [
 {
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "_Fusion Plan_",
"text": "Unlimited calls on landline and mobile 25GB data on mobile"
         }
       }
     ],
     "inputHint": "acceptingInput"
   }
 }
}

Hero Card 07 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
             "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios. This test try to understand how the channel render different links included in the message. https://aura.telefonica.com/es/",
            "images": [
              {
                "url": "https://jira.tid.es/secure/attachment/1778109/Group%2043%403x.png"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 08 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios.",
            "images": [
              {
                "url": "https://jira.tid.es/secure/attachment/1778109/Group%2043%403x.png"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 09 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios.",
            "images": [
              {
                "url": "https://media.tenor.com/images/c51500433e6f6fff5a8c362335bc8242/tenor.gif"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 10 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios",
            "images": [
              {
                "url": ""
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 11 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "text": "This is a bodycopy to test different scenarios and the channel behaviour for this scenarios",
            "images": [
              {
                "url": "https://www.telefoa"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 12 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios. This test try to understand how the channel render different links included in the message. https://aura.telefonica.com/es/",
            "images": [
              {
                "url":"https://www.telefonica.com/documents/23283/145847600/Movistar-azul-horizontal-thumbnail.jpg/fe991fa4-368f-72fe-ae8a-39f1db7ad638?t=1587395483934",
"url":"https://www.telefonica.com/documents/153952/154445/lgo_o2_at.png/3d0e2966-1cd5-49e2-8ac8-59ce69768bc4?t=1438154882691",
"url":"https://www.telefonica.com/documents/23283/139117659/Vivo-logo-thumbnail.jpg/e311e281-9c90-0a79-6531-aa357740a63f?version=1.1&t=1577957654404" 
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 13 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
 
  {
"contentType": "application/vnd.microsoft.card.hero",
 
"content": {
"title": "**iPhone 7 Apple iPhone**",
"text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product\n\n\n**Price: 512,34$**",
"images": [
{
"url": "https://jira.tid.es/secure/attachment/1778109/Group%2043%403x.png" 
           }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
 
  {
"contentType": "application/vnd.microsoft.card.hero",
 
"content": {
"title": "**Samsung Galaxy S21 Ultra 5G**",
"text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product\n\n\n**Price: 405,50$**",
"images": [
{
"url": "https://images.samsung.com/my/smartphones/galaxy-s21/buy/s21_family_kv_pc_img.jpg?imwidth=2560" 
           }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
 
  {
"contentType": "application/vnd.microsoft.card.hero",
 
"content": {
"title": "**Apple iPhone 12 Pro Max 5G**",
"text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product\n\n\n**Price: 905,50$**",
"images": [
{
"url": "https://www.apple.com/newsroom/images/product/iphone/standard/Apple_iphone12pro-pacific-blue_10132020_Full-Bleed-Image.jpg.large_2x.jpg" 
           }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 14 JSON file

"attachments": [
  {
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "**iPhone 7 Apple iPhone**",
"text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product",
 "buttons": [
                    {
                        "type": "openUrl",
                        "value": "https://www.movistar.es/",
                        "title": "Check Movistar app for more details"
                    }
                ]
            }
        }
   ]

Hero Card 15 JSON file

{
   "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "**iPhone 7 Apple iPhone**",
            "subtitle": "**Price**:",
            "text": "**Description**: \n7,11,9 cm (4,7) / 128 GB / 25\n Megapixel camera / Retina display / Apple red Product"
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }
}

Hero Card 16 JSON file

{
  "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios.",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.hero",
      "content": {
        "text": "This is a bodycopy to test different scenarios  and the channel behaviour for this scenarios.",
        "images": [
          {
            "url": "https://jira.tid.es/secure/attachment/1778109/Group%2043%403x.png"
          }
        ]
      }
    }
  ]
}

Custom card 01 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "postBack",
                "title": "Fake suggestion 1___",
                "value": {
                  "name": "Fake suggestion 1___",
                  "text": "Fake suggestion 1___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_1",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 2___",
                "value": {
                  "name": "Fake suggestion 2___",
                  "text": "Fake suggestion 2___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_2",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 3___",
                "value": {
                  "name": "Fake suggestion 3___",
                  "text": "Fake suggestion 3___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_3",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              }
            ]
          },
          "name": "SUGGESTIONS"
        }
      ]
    }
  }
}

Custom card 02 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "postBack",
                "title": "Fake suggestion 1___",
                "value": {
                  "name": "Fake suggestion 1___",
                  "text": "Fake suggestion 1___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_1",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 2___",
                "value": {
                  "name": "Fake suggestion 2___",
                  "text": "Fake suggestion 2___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_2",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 3___",
                "value": {
                  "name": "Fake suggestion 3___",
                  "text": "Fake suggestion 3___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_3",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 4___",
                "value": {
                  "name": "Fake suggestion 4___",
                  "text": "Fake suggestion 4___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_4",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 5___",
                "value": {
                  "name": "Fake suggestion 5___",
                  "text": "Fake suggestion 5___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_5",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              }
            ]
          },
          "name": "SUGGESTIONS"
        }
      ]
    }
  }
}

Custom card 03 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "postBack",
                "title": "Fake suggestion 1___",
                "value": {
                  "name": "Fake suggestion 1___",
                  "text": "Fake suggestion 1___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_1",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 2___",
                "value": {
                  "name": "Fake suggestion 2___",
                  "text": "Fake suggestion 2___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_2",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 3___",
                "value": {
                  "name": "Fake suggestion 3___",
                  "text": "Fake suggestion 3___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_3",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 4___",
                "value": {
                  "name": "Fake suggestion 4___",
                  "text": "Fake suggestion 4___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_4",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 5___",
                "value": {
                  "name": "Fake suggestion 5___",
                  "text": "Fake suggestion 5___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_5",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 6___",
                "value": {
                  "name": "Fake suggestion 6___",
                  "text": "Fake suggestion 6___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_6",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 7___",
                "value": {
                  "name": "Fake suggestion 7___",
                  "text": "Fake suggestion 7___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_7",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 8___",
                "value": {
                  "name": "Fake suggestion 8___",
                  "text": "Fake suggestion 8___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_8",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 9___",
                "value": {
                  "name": "Fake suggestion 9___",
                  "text": "Fake suggestion 9___",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_9",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 10__",
                "value": {
                  "name": "Fake suggestion 10__",
                  "text": "Fake suggestion 10__",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_10",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 11__",
                "value": {
                  "name": "Fake suggestion 11__",
                  "text": "Fake suggestion 11__",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_11",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              },
              {
                "type": "postBack",
                "title": "Fake suggestion 12__",
                "value": {
                  "name": "Fake suggestion 12__",
                  "text": "Fake suggestion 12__",
                  "type": "suggestion",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "fake_entity_suggestion_12",
                      "type": "ent.dialog-context"
                    }
                  ],
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog"
                }
              }
            ]
          },
          "name": "SUGGESTIONS"
        }
      ]
    }
  }
}

Custom card 04 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "title": "**iPhone Apple iPhone**",
            "text": "**Description:** \n128 GB  / Retina display / Apple red Product",
            "buttons": [
              {
                "type": "postBack",
                "title": "Reserve iPhone 1",
                "value": {
                  "name": "Reserve iPhone 1",
                  "text": "Reserve iPhone 1",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "buy-iphone1",
                      "type": "ent.dialog-context"
                    }
                  ]
                }
              },
              {
                "type": "postBack",
                "title": "Reserve iPhone 2",
                "value": {
                  "name": "Reserve iPhone 2",
                  "text": "Reserve iPhone 2",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "buy-iphone2",
                      "type": "ent.dialog-context"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Custom card 05 JSON file

{
  "card": {
    "hero": {
      "type": "message",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "subtitle": "**Price**: 999$",
            "title": "**iPhone Apple iPhone**",
            "text": "**Description:** \n128 GB  / Retina display / Apple red Product",
            "images": [
              {
                "url": "https://auraapnext8b2fe33b24.blob.core.windows.net/static-resources/libraries/factotum/default/images/iphone_red.png?sv=2018-11-09&si=static-resources-policy-ap-next&sr=c&sig=wtTBj9PX85%2BZiaJZIB4UqjnZh9BoU1acXcy8RyLp5kA%3D"
              }
            ],
            "buttons": [
              {
                "type": "postBack",
                "title": "Reserve iPhone 1",
                "value": {
                  "name": "Reserve iPhone 1",
                  "text": "Reserve iPhone 1",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "buy-iphone1",
                      "type": "ent.dialog-context"
                    }
                  ]
                }
              },
              {
                "type": "postBack",
                "title": "Reserve iPhone 2",
                "value": {
                  "name": "Reserve iPhone 2",
                  "text": "Reserve iPhone 2",
                  "intent": "intent.factotum-test.hero-card-custom-dialog",
                  "inputIntent": "intent.factotum-test.hero-card-custom-dialog",
                  "entities": [
                    {
                      "entity": "buy-iphone2",
                      "type": "ent.dialog-context"
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Templates

Template 01 Curl file

curl -X POST \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=AUTO_REPLY' \
  -d 'components: [{"type":"BODY","text":"Hi, I'm Aura.\nYour virtual assistant fom O2. Get personalised support, Get personalised support, view your bills and find out how much data you've got left. I am here to help!"}]' \
  -d 'name=test_global_aura_plain_text_no_header' \
  -d 'access_token=<your-access-token>' \
  -d 'language=en_US'

Template 01 JSON file

{
  "name": "test_global_aura_plain_text_no_header",
  "components": [
    {
      "type": "BODY",
      "text": "Hola, soy Aura.\nTu asistente virtual de O2. Obtén asistencia personalizada, consulta tus facturas y averigua cuántos datos te quedan. Estoy aquí para ayudarte."
    }
  ],
  "language": "es_ES",
  "status": "APPROVED",
  "category": "AUTO_REPLY",
  "id": "160734422709987"
}

Template 02 Curl file

curl -X POST \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=AUTO_REPLY' \
  -d 'components: [{"type":"BODY","text":"Before we carry on, I want you to know that your privacy is very important to me and I'm committed to look after your personal data."},{"type":"HEADER","format":"TEXT","text":"Your privacy matters"},{"type":"BUTTONS","buttons":[{"type":"URL","text":"Review terms and conditions","url":"https://www.movistar.es/particulares/centro-de-privacidad/"}]}]' \
  -d 'name=test_global_aura_plain_text_with_header_and_deeplink' \
  -d 'access_token=<your-access-token>' \
  -d 'language=en_US'

Template 02 JSON file

{
  "name": "test_global_aura_plain_text_with_header_and_deeplink",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Tu privacidad es importante"
    },
    {
      "type": "BODY",
      "text": "Antes de continuar, quiero que sepas que tu privacidad es muy importante para mí y me comprometo a cuidar tus datos personales."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Términos y condiciones",
          "url": "https://www.movistar.es/particulares/centro-de-privacidad/"
        }
      ]
    }
  ],
  "language": "es_ES",
  "status": "APPROVED",
  "category": "AUTO_REPLY",
  "id": "394312125348217"
}

Template 03 Curl file

curl -X POST \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=AUTO_REPLY' \
  -d 'components: [{"type":"BODY","text":"Hello, I'm Aura.\nYour virtual assistant from O2.\nI am contacting you to resolve the query *{{1}}* that you have made *{{2}}*.","example":{"body_text":[["about your bill","your call to 1004"]]}},{"type":"HEADER","format":"IMAGE","text":"https://{{1}}.blob.core.windows.net/static-resources/libraries/factotum/default/images/{{2}}?sv=2018-11-09&si={{3}}&sr=c&sig={{4}}","example":{"header_text":["auraapnext8b81ad27c3","iphone-12.png","aura-configuration-policy-ap-next","X53fPBD3fLZ4LqPVb8aeNJtTnj2O1nNfkyUVF3G/tMA%3D"]}},{"type":"BUTTONS","buttons":[{"type":"QUICK_REPLY","text":"Continue","example":"{ \"intent\": \"intent.common.greetings\" }"}]}]' \
  -d 'name=header_imagen_body_quick_reply' \
  -d 'access_token=<your-access-token>' \
  -d 'language=en_US'

Template 04 Curl file

curl -X POST \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=ACCOUNT_UPDATE' \
  -d 'components=[{"type":"BODY","text":"*Number: {{1}}*\nHey! You have {{2}} left from your {{3}} data allowance valid until {{4}}","example":{"body_text":[["+34 619866335","500 Mb","5 Gb","20/07/21"]]}},{"type":"FOOTER","text":"Type \"Next\" if you want to see more of your lines"},{"type":"BUTTONS","buttons":[{"type":"PHONE_NUMBER","text":"Call us","phone_number":"+34 619866335"},{"type":"URL","text":"More details","url":"https://www.movistar.es"}]}]' \
  -d 'name=test_global_aura_account_update_body_two_buttons' \
  -d 'access_token=<your-access-token>' \
  -d 'language=en_US'

Template 05 Curl file

curl -X POST \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=AUTO_REPLY' \
  -d 'components: [{"type":"BODY","text":"Your last bill is *{{1}}€*.\nClick to download and see the details.","example":{"body_text":[["58"]]}},{"type":"HEADER","format":"DOCUMENT","text":"https://{{1}}.blob.core.windows.net/static-resources/libraries/factotum/default/whatsapp-files/{{2}}?sv=2018-11-09&si={{3}}&sr=c&sig={{4}}","example":{"header_text":["auraapnext8b81ad27c3","PDF_Vertical.pdf","aura-configuration-policy-ap-next","X53fPBD3fLZ4LqPVb8aeNJtTnj2O1nNfkyUVF3G/tMA%3D"]}}]' \
  -d 'name=test_global_aura_header_document_body' \
  -d 'access_token=<your-access-token>' \
  -d 'language=en_US'

Template 06 Curl file

curl -X POST \
'https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d 'components=[{"type":"BODY","text":"If you have problems with your internet connection, follow the steps explained in the video.\n\nHas the problem been solved?"},{"type":"HEADER","format":"VIDEO"},{"type":"FOOTER","text":"Only for UHD decos"},{"type":"BUTTONS","buttons":[{"type":"QUICK_REPLY","text":"Yes"},{"type":"QUICK_REPLY","text":"Not yet"},{"type":"QUICK_REPLY","text":"Talk to an agent"}]}]' \
  -d 'name=test_global_aura_header_video_body_footer_tree_buttons' \
  -d 'access_token=<your-access-token>' \
  -d 'language=en_US'

Template 05 JSON file

{
  "name": "pnuevo_ofrecimiento_sinvincular_v6",
  "components": [
    {
      "type": "BODY",
      "text": "El producto que te propongo es {{1}} que incluye:\n\n- Fijo: {{2}}\n- Móvil: {{3}}\n- Internet: {{4}}\n- Televisión: {{5}}\n- Smartphone gama {{6}}\n\nY todo esto por {{7}}€/mes (IVA incluido).\n\n¿Te interesa este producto?"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Sí"
        },
        {
          "type": "QUICK_REPLY",
          "text": "No, quiero ver otros"
        }
      ]
    }
  ],
  "language": "es_ES",
  "status": "APPROVED",
  "category": "ACCOUNT_UPDATE",
  "id": "323717239403265"
}

Template 06 JSON file

{
  "name": "pnuevo_aceptacion_sinvincular_v2",
  "components": [
    {
      "type": "BODY",
      "text": "{{1}} a {{2}} y NIF{{3}}, solicitas el cambio a:\n\nFijo: {{4}}\nMóvil: {{5}}\nInternet: {{6}}\nTV: {{7}}\n\nArrendamiento a 36 meses de un terminal nivel {{8}}. En caso de devolución o baja anticipada se aplican las Condiciones Generales de Arrendamiento de Terminal Móvil en Fusión. Consulta los modelos en {{9}}\n\nPrecio: {{10}}€/mes (Precios con IVA)\n\nAceptas recibir tus facturas en formato electrónico. Puedes solicitar cambio a papel cuando desees.  \n\nCondiciones del servicio y política de privacidad: movistar.es/contratos y movistar.es/privacidad. \n\nAutorizas a hacer los cargos en tu cuenta bancaria.\n\nSi estás conforme pulsa “Acepto”"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Acepto"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Consultar a agente"
        }
      ]
    }
  ],
  "language": "es_ES",
  "status": "APPROVED",
  "category": "ACCOUNT_UPDATE",
  "id": "4208428555858233"
}

Suggestions

Suggestion 01 JSON file

{
      "type": "message",
      "text": "This is button.suggestion.01.",
      "attachmentLayout": "SUGGESTIONS",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "text": "This is button.suggestion.01.",
            "buttons": [
              {
                "type": "imBack",
                "title": "Top up"
              },
              {
                "type": "imBack",
                "title": "Talk with agent"
              },
              {
                "type": "imBack",
                "title": "My invoice"
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }

Suggestion 02 JSON file

{
  "button.suggestion.02": {
      "type": "message",
      "text": "This is button.suggestion.02.",
      "attachmentLayout": "SUGGESTIONS",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "postBack",
                "title": "Suggestion with 30 characters."
              },
              {
                "type": "postBack",
                "title": "This suggestion contains 50 characters, dont do it"
              },
              {
                "type": "postBack",
                "title": "This suggestion contains way more than 100 characters. Never do this please. User experience is horrible"
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }
   }

Suggestion 03 JSON file

{
   "button.suggestion.03": {
      "type": "message",
      "text": "This is button.suggestion.03.",
      "attachmentLayout": "SUGGESTIONS",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "postBack",
                "title": "Hola"
              },
              {
                "type": "postBack",
                "title": "Gracias"
              },
              {
                "type": "postBack",
                "title": "Adiós"
              },
              {
                "type": "postBack",
                "title": "Ayuda"
              },
              {
                "type": "postBack",
                "title": "Esto va a greetings",
                "value": { "intent": "intent.common.greetings" }
              },
              {
                "type": "postBack",
                "title": "Connection issue"
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }
  }

Suggestion 04 JSON file

{
"button.suggestion.04": {
      "type": "message",
      "text": "This is button.suggestion.04.",
      "attachmentLayout": "SUGGESTIONS",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }
   }

Suggestion 05 JSON file

{
"button.suggestion.05": {
      "type": "message",
      "text": "This is button.suggestion.05.",
      "attachmentLayout": "SUGGESTIONS",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "postBack",
                "title": ""
              },
              {
                "type": "postBack",
                "title": ""
              },
              {
                "type": "postBack",
                "title": ""
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }
   }

Actions

Actions 01 JSON file

{"text": "This should be the insight text.","attachments": [
  {
    "contentType": "application/vnd.microsoft.card.hero",
     "content": {


     "buttons": [
     {
    "type": "imBack",
    "title": "Yes"
    },
{
    "type": "imBack",
    "title": "No"
      }
  ]
  }
  }
 ]
}

Actions 02 JSON file

{"text": "This should be the insight text.",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.hero",
            "content": {
 
                "buttons": [
                    {
                        "type": "imBack",
                        "title": "Yes"
                    },
                    {
                        "type": "imBack",
                        "title": "No"
                    },
                    {
                        "type": "imBack",
                        "title": "Cancel"
                    }
                ]
            }
        }
    ]
}

Actions 03 JSON file

    {
      "button.actions.03": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "imBack",
                "title": "Yes, I agree with 30 characters"
              },
              {
                "type": "imBack",
                "title": "This action contains 50 characters, dont do it pls"
              },
              {
                "type": "imBack",
                "title": "This action button contains way more than 100 characters. Never do this please. User experience is horrible."
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }
    }

Actions 04 JSON file

{
  "button.actions.04": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "imBack",
                "title": "Yes"
              },
              {
                "type": "imBack",
                "title": "No"
              },
              {
                "type": "imBack",
                "title": "Maybe"
              },
              {
                "type": "imBack",
                "title": "Didn't understand"
              },
              {
                "type": "imBack",
                "title": "Don't know"
              },
              {
                "type": "imBack",
                "title": "Cancel"
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }
    }

Actions 05 JSON file

{
"button.actions.05": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": []
          }
        }
      ],
      "inputHint": "expectingInput"
    }
    }

Actions 06 JSON file

{
  "button.actions.06": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "imBack",
                "title": ""
              },
              {
                "type": "imBack",
                "title": ""
              },
              {
                "type": "imBack",
                "title": ""
              }
            ]
          }
        }
      ],
      "inputHint": "expectingInput"
    }}

External buttons

External button 01 JSON file

{
"button.external.01": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "openUrl",
                "title": "**Google**",
                "value": "https://www.google.com"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }

External button 02 JSON file

{
"button.external.02": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "openUrl",
                "title": "Url button with 30 characters",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "This url button contains 50 characters, dont do it",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "This url button contains way more than 100 characters. Never do this please. User experience is horrible",
                "value": "https://www.google.com"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
}

External button 03 JSON file

{
"button.external.03": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "openUrl",
                "title": "Google 1",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "Google 2",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "Google 3",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "Google 4",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "Google 5",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "Google 6",
                "value": "https://www.google.com"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }

External button 04 JSON file

{
"button.external.04": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": []
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }

External button 05 JSON file

{
"button.external.05": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "openUrl",
                "title": "",
                "value": "www.google.com"
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }

External button 06 JSON file

{
"button.external.06": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "openUrl",
                "title": "Google",
                "value": ""
              }
            ]
          }
        }
      ],
      "inputHint": "acceptingInput"
    }
  }

External button 07 JSON file

{
    "button.external.07": {
      "type": "message",
      "text": "This should be the insight text.",
      "attachmentLayout": "list",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.hero",
          "content": {
            "buttons": [
              {
                "type": "openUrl",
                "title": "**Url button with 30 characters.**",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "**This url button contains 50 characters, dont do it**",
                "value": "https://www.google.com"
              },
              {
                "type": "openUrl",
                "title": "**This url button contains way more than 100 characters. Never do this please. User experience is horrible**",
                "value": "https://www.google.com"
              }
            ]
          }
        }
      ]
    }
  }

Mix messages

Mix message 01 JSON files

Message 1: Insight

{
  "text": "Loremipsumdolorsitamet, consecteturadipiscingelit. Crasnuncelit, auctorutlectusvel, blanditeleifendturpis. Nammalesuadacursusarcu. Pellentesqueeu magnanonlectuseleifendmattisinneclibero. Quisquelaciniaeget ligulaaliquamaccumsan. "
}

Message 2: Herocards

Hero Card 01 JSON file

Message 3: Suggestions with 1-3 options and less than 20 characters

Suggestion 01 JSON file

Mix message 02 JSON files

Message 1: Insight

{
  "text": "Loremipsumdolorsitamet, consecteturadipiscingelit. Crasnuncelit, auctorutlectusvel, blanditeleifendturpis. Nammalesuadacursusarcu. Pellentesqueeu magnanonlectuseleifendmattisinneclibero. Quisquelaciniaeget ligulaaliquamaccumsan. "
}

Message 2: Herocards

Hero Card 01 JSON file

Message 3: suggestions with 4-10 options and less than 20 characters

Suggestion 03 JSON file

Mix message 03 JSON files

Message 1: Insight

{
  "text": "Loremipsumdolorsitamet, consecteturadipiscingelit. Crasnuncelit, auctorutlectusvel, blanditeleifendturpis. Nammalesuadacursusarcu. Pellentesqueeu magnanonlectuseleifendmattisinneclibero. Quisquelaciniaeget ligulaaliquamaccumsan. "
}

Message 2: Herocards

Hero Card 01 JSON file

Message 3: suggestions with more than 10 options and/or more than 20 characters

Suggestion 02 JSON file

Mix message 05 JSON files

Message 1: HeroCards

Hero Card 03 JSON file

Message 2: Herocards

Hero Card 03 JSON file

Message 3: Herocards

Hero Card 03 JSON file

Message 4: suggestion

Suggestion 01 JSON file

Docs:

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

Selection connectors

Introduction

Selector connectors allow, when included on a pipeline, to specify which path of the pipeline is applied depending on a certain parameter.

Currently, only one selection connector is developed in Aura NLP: Domain selector connector.

Domain selector connector

Description

The domain selector connector allows specifying which path of the pipeline is applied depending on the recognized domain. Therefore, it has to be preceded by a domain classifier step.

In this example, once the Domain Classifier has recognized the domain, the Domain Selector stage comes into play. In case the recognized domain is “domain1”, the flow continues to “Pipeline1”. Otherwise, if domain is “domain2” or “domain3”, “Pipeline2” or “Pipeline 3” are selected respectively as the following stage.

Path

auracog_pipelines.pipelines.joint.selectors.DomainSelectorPipeline

Configuration

This connector requires a specific configuration with the following fields in the dynamic NLP pipeline pipeline.json

elements: definition of every element composing the pipeline (stages and joints). It must include:
- Element name. In this case,
  .
  - type: It must be set to joint
  - classpath: path to be included in order to use this stage: auracog_pipelines.pipelines.joint.selectors.DomainSelectorPipeline
  - links: links between each specific domain and its corresponding pipeline.
  - args section: dictionary that must be included after the class path with a key named selection_map that defines a correspondence between domains and different pipelines identified by its position as a child of the pipeline in the links field. One of these domains must be default. In this case, if no domain is established, this path within the pipeline is followed.

Note that a non-existent pipeline, or missing default pipeline results in an error.

It is always required to check two items:

The correspondence is right (be aware that the index in the selection_map subsection starts with 0)
The referred pipelines exist in links section of the pipeline.json file.

Example:

"elements": {
   "<DomainSelectorPipelineName>": {
       "type": "joint",
       "classpath": "auracog_pipelines.pipelines.joint.selectors.DomainSelectorPipeline",
       "args": {
          "selection_map": {
                "<domain1>": <Index of pipeline desired for domain 1>,
                "<domain2>": <Index of pipeline desired for domain 2>,
                ...
                "<domainN>": <Index of pipeline desired for domain N>,
                "default": <Index of pipeline desired for other domains>
                               }
                                  }
 }
}

In the example:

If domain is 1, then pipeline continues with element defined in position 0.
If domain is 2, then pipeline continues with element defined in position 1.

Docs:

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

Train Aura to understand: Use cases development over Aura NLP

Guidelines for every step in the process for personalized use cases development over Aura NLP, in order to make Aura understand the users’ requests.

Related documents
📄 Aura NLP descriptive documentation

Process at a glance

Previous requisites

. Get sure your system has the required technical resources
. Install the Aura NLP Virtual Machine
. Generate a local branch for the NLP data repository

Generate NLP model

. Build up the dynamic pipeline
. Configure the NLP model
. Generate training files, test set files and dictionaries

Train NLP model

. Train the understanding model in order to make it understand properly the users' requests

Test NLP model

. Evaluate the accuracy of the NLP model locally
. If results are satisfactory, it must be also validated by Aura Global Team

Deploy NLP package

. Merge and generate the NLP package containing the understanding model
. Deploy the new package to make it available

Introduction

This section includes the detailed process for the development of use cases over aura-nlp together with all the complementary stages that linguists and NLP experts need for this purpose.

The following figure schematically shows the workflow for the development of a use case over Aura NLP, where every stage is fully described in succeeding sections.

Firstly, get sure you fulfil all the prerequisites for the configuration of the NLP development environment.
Afterwards, follow the orderly stages in use cases development over Aura NLP.

If you are interested in a specific process, access directly to its documentation here:

Catalog of components for NLP pipelines: catalog of stages, connectors and normalization pipelines that can be used to compose the NLP pipeline.
Aura NLP entities catalogs: Description of entities catalogs, input for Aura NLP dictionaries.
Aura NLP dictionaries: Description of dictionaries, used to recognize entities.
Use of Grammars in Aura NLP: guidelines for using Grammars in an NLP model.
Complementary processes: processes that may be carried out over external software when developing a use case and procedures followed by the Aura NLP Global Team.

Docs:

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

Guidelines for the use of Abacus 1.0.0.

After the Abacus set-up, learn how to use the tool with our guidelines.

Open Abacus

Open the NLP Virtual Machine.

Execute the following commands in the console:

cd ${Root_project}/tools
./run_web_trainings.sh

Abacus is now opened.

Discover Abacus main screen

Create a new Pull Request

Enter Abacus and select “New Pull Request” as your working mode.
In the main interface, select the channel where your understanding model is.

Train your understanding model.
When the training is finished, select “Results” in the drop-down menu and access to the results of the accuracy tests.
- End-to-end tests (accuracy of the overall NLP model)
Evaluate the accuracy of your model:

Check in “last test” the overall accuracy related to the last test performed in the tool.
Click on each specific error in “last test report” to access to detailed information.
Use the filters to visualize errors per type, intent obtained or intent expected.

Test your NLP model locally (Abacus simulator).
Once your model is trained, you can use the Simulator to launch and test your pipeline locally and make a real-time evaluation of accuracy in the recognition of a specific statement.
- Open the simulator.
- Type a phrase.
- Check how your model recognizes it.
When the accuracy is satisfactory, publish your model:

Press the “PUBLISH” button.
Create your Pull Request inserting the type, related JIRA issue, title and description and publish it.
If everything goes right, your PR is published. You can also see the details in Github.

Edit an existing Pull Request

Enter Abacus and select “Edit existing Pull Request” as your working mode.
Select your intended Pull Request. You can open it from Abacus or from GitHub to see its details.
Now, you can work over it as explained in Create a new Pull Request section, from step 2 onwards.

Abacus additional information

When Abacus is started, the API is available in: http://127.0.0.1:4000 (*)

(*) The port is variable, with values in the range: 4000 - 4100

The API documentation is included in Aura NLP API definition.

Abacus troubleshooting

Logs files

All the operations carried out with Abacus are recorded in the logs file: ${Root_project}/server.log

If an error occurs, Abacus will show this message:
Clicking on “Download”, you can access to the log report and check the error for fixing it.
If, the problem persists, contact the Global Support Team and provide them with the report.
When it is solved, press “Reload”, to continue using Abacus.

Git conflicts

If the remote branch has changes that have not been updated in the local working branch, Github detects this situation as a conflict when publishing, and is not able to recognize which are the correct changes.

The following pop up will appear after clicking on “publish”.

Clicking on “Download”, you will get the file ${Root_project}/server.log, where you can check the errors that have occurred and try to solve them.

!  [rejected]    <<working-branch>>  ->  <<working-branch>> (fetch first)
error: failed to push some refs to 'git@github.com:Telefonica/aura-nlpdata-global.git'

Conflicts in server.log must be resolved locally using the editor:

Open a terminal in code editor. Make sure the branch in terminal is the correct working branch.
Move changes from the remote branch to local:
git pull origin <<working-branch>>
A message with a list of files with conflicts is shown.
Open each file and right-click to access the conflicts resolver.
Resolve the conflict. You can include texts from the local branch (left) or from the remote one (right) or discard both and copy what is needed.
Once conflicts are resolved, launch the following command to review the status of the local branch and check that all the conflicts are fixed in the response message:
git status
When all the conflicts are resolved, commit changes:
git commit –m "[[feat]] resolve conflicts: <<description of changes>>"
Push to update changes to the remote branch:
git push origin <<working-branch>>
A message with all the details will appear.
If everything is solved, now restart the web server and continue with the existing Pull Request.

Docs:

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

Aura develop utilities

Description of aura-develop-utilities

Introduction

aura-develop-utilities is a package belonging to aura-common-utilities that includes utilities used for different development purposes.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-develop-utilities/

How to install aura-develop-utilities package

$ git clone https://github.com/Telefonica/aura-common-utilities.git

$ cd aura-common-utilities/packages/aura-develop-utilities

Available utilities

List of utilities in the aura-develop-utilities package:

aura-client-generator utility: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-develop-utilities/src/aura-client-generator/

Docs:

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

aura-crypto-adapter utility

aura-crypto-adapter utility provide methods for encrypting and decrypting data.

Introduction

aura-crypto-adapter is a utility that provides methods for encrypting and decrypting data using a specified encryption algorithm and managing vectors associated with the encryption process. It also includes a method for generating checksums using different algorithms.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-utilities/src/aura-crypto-adapter/

Configuration

The following variables are required for the configuration of aura-crypto-adapter. They belong to aura-bot environment variables.

AURA_ENCRYPTION_KEY - Mandatory
AURA_ENCRYPTION_IV_LENGTH - Mandatory
AURA_ENCRYPTION_ALGORITHM - Mandatory

Basic usage

Import the CryptoAdapter class:

import { CryptoAdapter } from '@telefonica/aura-crypto-adapter';

Create an instance of cryptoAdapter by providing the required configuration variables.
```
const cryptoAdapter = new CryptoAdapter(configuration);
```
To encrypt information, call the encrypt method of the cryptoAdapter instance, passing the information and an optional key (if it is needed to use a different one than the given on configuration).
```
const encryptedToken = cryptoAdapter.encrypt(information);
```
To decrypt information, use the decrypt method of the cryptoAdapter instance, again providing an optional key.
```
const decryptedInformation = cryptoAdapter.decrypt(encryptedToken);
```
Checksum Verification: If you need to verify the integrity of the data, you can use the checksum method of the CryptoAdapter class. Store or transmit the checksumValue along with the encrypted data. When decrypting, calculate the checksum again and compare it with the stored value to ensure data integrity.
```
const checksumValue = CryptoAdapter.checksum(data);
```

Run tests

You can validate run jest testing tools with the script:

$ npm run test

Linter

You can validate the code using the eslint tool with the script:

$ npm run lint

Versioning

We use SemVer for versioning.

For all available versions, look at the tags in this repository.

Docs:

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

Guidelines for building a dialog that uses async APIs

Orderly steps for building an Aura Bot dialog that require to call asynchronous APIs

Introduction to asynchronous APIs

Asynchronous APIs are defined as APIs that do not provide the information back immediately, but with a certain standby time as they must perform a specific task derived from the user’s request. When the execution of this task is finished, these APIs invoke a callback and pass to the dialog the result of the task accomplishment.

The call to an asynchronous API must be included in the use case dialog and the payload from the API will be sent to aura-bridge, which is in charge of delivering it to the dialog that invoked this API.

This functionality can be useful, for example, in use cases that need to call to self-diagnostics APIs.

ℹ️ Current requisites:

This functionality only applies to Kernel APIs.
The correct operation implies that the dialog is in bypass mode.

An example of the usefulness of asynchronous APIs is shown below:

The user asks Aura: “Test my optical fiber connection” aura-bot recognizes this request and triggers a specific dialog. The dialog, that must be configured in bypass mode, calls an asynchronous API. The API takes T seconds in answering as Aura has to perform certain verification tests.
After that time, the API sends a callback to the dialog with a text that include the result of the verification tests and offers different solutions for the user to choose.
The user selects one of the options and the intended answer is provided to her.

How to call asynchronous APIs in a dialog

Follow these guidelines in order to make your dialog call an asynchronous API.

1. Check purposes and scopes

Firstly, you should add in the channel configuration (aura-configuration-api) all the necessary purposes and scopes in order to invoke the APIs.

⚠️ It must be done for all the intended channels* that will use the dialog.

2. Call asynchronous APIs in the dialog

For including asynchronous APIs in the dialog, it must work in bypass mode. This bypass mode must be started when the first call to the asynchronous API is made.

    const callbackId = stepContext.context.activity.id;
    const bypass: Bypass<BypassModelData> = await Bypass.initialize(
            stepContext.context,
            this.timeout,
            { callbackId },
            'asyncCallback',
            BypassState.Init,
            getLiteral(stepContext?.context)('factotum:bypass.close.words'));
        const message = this.message4pCreate;
        message.diagnosis_callback_url = getAsyncCallbackUrl(
                stepContext.context, this.configuration, callbackId);
        const response = await this.sendMessageTo4p(stepContext, this.url4p, message, corr);
        // Update bypassmode (if connection is ok)
        bypass.state = BypassState.Bypass;
        bypass.data.tecnicalProblemId = response?.body?.id;
        await bypass.updateBypass(stepContext?.context, false);

This API has a parameter to send the callback where the response is received, in this case aura-bridge. To build this URL, there is a getAsyncCallbackUrl(@telefonica/aura-bot-common) method, belonging to the bridge-utils utility. This will return the callback URL based on the context, the configuration and an identifier that will be sent in the answer.

message.diagnosis_callback_url = getAsyncCallbackUrl (
                 stepContext.context, this.configuration, callbackId);

In each execution of the dialog, this must be finished (as bypass mode requires closing the dialog in each execution), so that it is reactivated by aura-bot when it finds the bypass mode.

Communication flow

The following diagram shows the request flow of a message to a dialog invoking an asynchronous API:

sequenceDiagram
    actor User
    participant Whatsapp
    participant 4P
    participant Bridge
    participant Bot
    participant Dialog
    User ->> Whatsapp: message
    Whatsapp ->> 4P: message
    4P ->> Bridge: message + apiKey + channelId
    Bridge ->> 4P: response 200
    Bridge ->> Bot: message + channelId
    Bot ->> Dialog: message
    Dialog ->> 4P: request async + callback bridge
    4P ->> Dialog: response 200
    Note right of 4P: when 4p finishes the request sends the response to the indicated callback (bridge)
    4P ->> Bridge: response request async
    Bridge ->> 4P: response 200
    Bridge ->> Bot: response request async
    Note right of Bridge: the response is sent as payload
    Bot ->> Bridge: response 200
    Bot ->> Dialog: response request async

Example of a dialog calling an asynchronous API

This is a dialog’s example that makes calls to an asynchronous API.

Firstly, the dialog checks in which bypass state is:

    const corr = ContextUtils.getCorrelator (stepContext.context);
    try {
        const bypass = await Bypass.loadBypass (stepContext.context);
        switch (bypass.state) {
            case BypassState.Off:
            case BypassState.Init: {
                await this.onInit (stepContext, corr);
                break;
            }
            case BypassState.Bypass: {
                await this.onByPass (stepContext, corr);
                break;
            }
            case BypassState.Closed: {
                await this.onClosed (stepContext, corr);
                break;
            }
        }
    } catch (err) {
        await stepContext.context.sendActivity ('Error async event 4p');
        this.logger.error ({error: 'Error async event 4p', stck: err, corr});
    }
    return await stepContext.endDialog ();

If bypass mode is not started, the asynchronous API call will be sent and the bypass mode will be initialized.

    private async onInit (stepContext: WaterfallStepContext, corr: string) {
        try {
            const callbackId = stepContext.context.activity.id;
            const bypass: Bypass <BypassModelData> = await Bypass.initialize (
                stepContext.context,
                this.timeout,
                {callbackId},
                'asyncCallback',
                BypassState.Init,
                getLiteral (stepContext? .context) ('factotum: bypass.close.words'));
            const message = this.message4pCreate;
            message.diagnosis_callback_url = getAsyncCallbackUrl (
                stepContext.context, this.configuration, callbackId);
            const response = await this.sendMessageTo4p (stepContext, this.url4p, message, corr);
            // Update bypassmode (if connection is ok)
            bypass.state = BypassState.Bypass;
            bypass.data.tecnicalProblemId = response? .body? .id;
            await bypass.updateBypass (stepContext? .context, false);
            this.logger.info ({msg: `Bypass initializated`, corr});
        } catch (err) {
            await Bypass.closeBypass (stepContext.context);
            await stepContext.context.sendActivity ('Error call async api 4p');
            this.logger.error ({msg: 'Error call async api 4p', error: err.message, stck: err, corr});
        }
    }

If aura-bot is in bypass mode, the dialog could receive users’ messages. In the example, messages are ignored, but at this point the dialog can receive the response of the asynchronous API. If the sent identifier matches, the content will be sent to the user, thus ending the bypass mode. In the bypass.data element, information can be stored in order to be used between different bypass cycles.

   private async onByPass (stepContext: WaterfallStepContext, corr: string) {
        const payload = ChannelDataUtils.getPayloadAsyncCallback(stepContext.context);
        const bypass: Bypass <BypassModelData> = await Bypass.loadBypass (stepContext.context);
        if (payload && bypass.data.callbackId === payload.callbackId) {
            const payloadText = JSON.stringify (payload);
            this.logger.debug ({msg: `Send activity message $ {payloadText}`, corr});
            await stepContext.context.sendActivity (payloadText);
            await this.cancelTecnicalProblem (stepContext, corr);
        } else {
            this.logger.debug ({msg: `Ignore $ {stepContext? .context? .activity? .text}`, corr});
        }
    }

If the bypass has ended, the bypass time has expired or the user has used one of the closing terms, the dialog must close the bypass mode and perform the appropriate operations. In the following example, a message is sent to the user.

    private async onClosed (stepContext: WaterfallStepContext, corr: string) {
        await Bypass.closeBypass (stepContext.context);
        await stepContext.context.sendActivity ('Bypass closed');
    }

Docs:

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

Deployment of an agent in ATRIA

Guidelines for the deployment of newly created agents in ATRIA

Introduction

The current document includes comprehensive guidelines that serves as the foundational framework for the deployment of customized agents within ATRIA.

To deploy an agent in the aura config provisioning it is necessary to generate the following files in the corresponding folders.

Agents Base

In this folder, it is necessary to include the agents that are available to build. To do this, a json file must be generated with the data of this new agent.

Here is an example.

{
  "id": "XXXX-XXXX-XXXX-YYYYYYYYYYYYYY",
  "name": "test-agent",
  "description": "An agent test",
  "language": "python",
  "version": "1.0.0"
}

Where:

id: Unique identifier for the agent.
name: Name of the agent.
description: Description of the agent.
language: Programming language used for the agent.
version: Version of the agent.

These fields can also be added, removed or edited from the api. Also changes made by the api directly will not be persisted between releases.

Agents Deployment

In this folder, developers must define the agent to be deployed, associated with the [Docker image version]((/docs/atria/technical-guidelines/agents-management/agents-technical-development/docker-image/) previously created.

For this purpose, generate a json file with the data of this new agent.

Here is an example.

{
   "id": "XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "name": "test-agent",
   "config": {},
   "secrets": {},
   "image": "XXXX/agent-test",
   "tag": "X.X.X"
 }

Where:

id: Unique identifier for the agent.
name: Name of the agent.
config: Assign configuration assigned to in the agent’s environment (can be empty).
secrets: Assign secrets assigned to in the agent’s environment (can be empty).
image: Docker image of the agent.
tag: Tag of the Docker image.

These fields cannot be updated from the api.

Agents

In this folder, developers must include the information regarding te agent to be deployed, together with its configuration and information.

You can display the same agent image but with different information or configuration.

Here is an example.

{
     "id": "XXXX-XXXX-XXXX-XXXXXXXXXXXX",
     "name": "test-agent",
     "deploymentName": "test-deployment-agent",
     "description": "A test agent",
     "communication": {
         "communicationType": "http"
     },
     "agentBase": {
         "name": "test-agent",
         "configuration": {}
     }
 }

Where:

id: Unique identifier for the agent.
name: Name of the agent. This value is the name we want to give to the agent and is not related to the name we have at code level. Therefore, we can deploy several different agents with the same code base.
deploymentName: Name of the deployment of the agent, this value allows grouping several agents to the same deployment name.
description: Description of the agent.
communication: Communication type of the agent, in this case it is HTTP.
agentBase: Information about the base agent, including its name and configuration.
agentBase.name: Name of the base agent, this value allows you to associate the agent with the image of the agent you want to deploy. This value is associated with the name that comes by reference with the value of the get_class_ref of the developed agent.
agentBase.configuration: Configuration parameters for the agent (can be empty).

These fields can also be added, removed or edited from the api. Also changes made by the api directly will not be persisted between releases.

Applications

For the agent to be used in ATRIA, it must be associated to an existing application.

For this purpose, within the general process for the configuration of an application, edit the field agents with the list of agents’ identifiers to be associated to the application.

Here is an example.

{
     "brand": "ZZZZ",
     "id": "YYYY-YYYY-YYYY-YYYYYYYYYYYY",
     "name": "test-agent-app",
     "agents": [
         "XXXX-XXXX-XXXX-XXXXXXXXXXXX"
     ]
}

These fields can also be added, removed or edited from the api. Also changes made by the api directly will not be persisted between releases.

Docs:

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

Disambiguation connector

Description

The disambiguation connector is a joint stage that allows disambiguation between different pipelines (therefore, between different recognizers).

The general behavior of this connector is shown as follows:

It executes in parallel the different pipelines.
When the execution of all the pipelines is finished, the connector will carry out a disambiguation by intents, comparing the top results from the execution of the pipelines.
However, take into account that, if there is a blacklist of intents, this behavior changes, as explained in the following section.

Disambiguation connector with a blacklist of intents

Aura NLP allows the integration of configurable blacklists of intents for a custom behavior of disambiguation. In this case, the disambiguation mechanisms will not apply for the intents included in the blacklist.

The use case constructors can edit a blacklist of intents in the nlp.json configuration file, filling the parameter intent_blacklist.

When there is a blacklist of intents, the disambiguation connector behaves as explained below:

It executes in parallel the different pipelines, with their corresponding stages.
The recognized intents from each pipeline are extracted (unless they have a None intent).
If the top scored intent of these pipelines is included in the intent_blacklist or its score is greater than the exact_match threshold, then this intent is returned.
If the top intent is not included in the intent_blacklist, then the predefined values of the configuration parameters come into play:
- All the intents between the disambiguation_margin and the top score, and not present in the intent_blacklist, are selected.
- If there is only one intent, it will be returned in a pipeline message.
- If there is more than one intent, a pipeline message with the intent intent_template and a score of 1.0 is assigned. This pipeline message will contain nor entities, neither domains, but it will contain all the selected intents in pipeline messages as options.

Path

auracog_pipelines.pipelines.joint.disambiguation.DisambiguationPipeline

Configuration

This stage requires a specific configuration in the dynamic NLP pipeline pipeline.json. The following parameters are required for this stage:

elements: definition of every element composing the pipeline (stages and joints). It must include:
- Element name. In this case, JointDisambiguation
- type: It must be set to joint
classpath: path to be included in order to use this stage: auracog_pipelines.pipelines.joint.disambiguation.DisambiguationPipeline
args section: dictionary with the following fields:
- exact_match: If the intent with the highest score is greater than this value, the result is this intent. Float number.
- disambiguation_margin: Margin between the highest score and the lower score considered for the response. Float number.
- intent_template: Name of the intent that the stage returns when there are multiple options as response. String.
- intent_blacklist: list of intents that will be removed in case there are other options. If there are no blacklisted intents it will have to be an empty list. List of strings.

See two examples of configuration for the disambiguation connector:

Disambiguation connector - Example 1

{
  "name": "Example",
  "initial_node_id": "JointDisambiguation",
  "elements": {
    "JointDisambiguation": {
      "type": "joint",
      "classpath": "auracog_pipelines.pipelines.joint.disambiguation.DisambiguationPipeline",
      "args": {
        "exact_match": 0.95,
        "disambiguation_margin": 0.2,
        "intent_template": "intent.disambiguation",
        "intent_blacklist": ["intent.intent1", "intent.intent1", ...]
      }
    },
    "OtherStage1": {
      "type": "stage",
      "classpath": "..."
    },
    "OtherStage2": {
      "type": "stage",
      "classpath": "..."
    },
    ...
  },
  "links": {
    "JointDisambiguation": [
      "OtherStage1",
      "OtherStage2",
      ...
    ]
  }
}

Disambiguation connector - Example 2

Example for a disambiguation margin equal to 0.2

Input data model

[
    {
        'query': 'original Phrase',
        'channel': 'mp',
        'intent_result': {
            'entities': [
                {
                    'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
                },
                {
                    'entity': 'name2', 'type': 'type2', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label2'
                }
            ],
            'top_result': {'intent': 'intent.tv.search', 'score': 0.96},
            'intents': [
                {'intent': 'intent.tv.search', 'score': 0.96},
                {'intent': 'intent.tv.display', 'score': 0.95},
                {'intent': 'intent.tv.launch', 'score': 0.60}
            ]
        },
        'domain_result': {}
    },
    {
        'query': 'original Phrase',
        'channel': 'mp',
        'intent_result': {
            'entities': [
                {
                    'entity': 'name3', 'type': 'type3', 'score': 0.89, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label3'
                },
                {
                    'entity': 'name4', 'type': 'type4', 'score': 0.76, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label4'
                }
            ],
            'top_result': {'intent': 'intent.tv.display', 'score': 0.94},
            'intents': [
                {'intent': 'intent.tv.display', 'score': 0.94},
                {'intent': 'intent.tv.launch', 'score': 0.70}
            ]
        },
        'domain_result': {}
    },
    {
        'query': 'original Phrase',
        'channel': 'mp',
        'intent_result': {
            'entities': [
                {
                    'entity': 'name5', 'type': 'type5', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label5'
                },
                {
                    'entity': 'name6', 'type': 'type6', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label6'
                }
            ],
            'top_result': {'intent': 'intent.tv.search', 'score': 0.81},
            'intents': [
                {'intent': 'intent.tv.search', 'score': 0.81},
                {'intent': 'intent.tv.display', 'score': 0.75}
            ]
        },
        'domain_result': {}
    },
    {
        'query': 'original Phrase',
        'channel': 'mp',
        'intent_result': {
            'entities': [
                {
                    'entity': 'name7', 'type': 'type7', 'score': 0.99, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label7'
                }
            ],
            'top_result': {'intent': 'intent.tv.launch', 'score': 0.60},
            'intents': [
                {'intent': 'intent.tv.launch', 'score': 0.60}
            ]
        },
        'domain_result': {}
    }
}
]

Output data model (2 intents fulfil the predefined criteria)

{
    'query': 'original Phrase',
    'channel': 'mp',
    'intent_result': {
        'entities': [],
        'top_result': {'intent': 'intent.disambiguation', 'score': 1.0},
        'intents': [
            {'intent': 'intent.disambiguation', 'score': 1.0}
        ]
    },
    'domain_result': {},
    'options': [
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name1', 'type': 'type1', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label1'
                    },
                    {
                        'entity': 'name2', 'type': 'type2', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label2'
                    }
                ],
                'top_result': {'intent': 'intent.tv.search', 'score': 0.96},
                'intents': [
                    {'intent': 'intent.tv.search', 'score': 0.96},
                    {'intent': 'intent.tv.display', 'score': 0.95},
                    {'intent': 'intent.tv.launch', 'score': 0.60}
                ]
            },
            'domain_result': {}
        },
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name3', 'type': 'type3', 'score': 0.89, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label3'
                    },
                    {
                        'entity': 'name4', 'type': 'type4', 'score': 0.76, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label4'
                    }
                ],
                'top_result': {'intent': 'intent.tv.display', 'score': 0.94},
                'intents': [
                    {'intent': 'intent.tv.display', 'score': 0.94},
                    {'intent': 'intent.tv.launch', 'score': 0.70}
                ]
            },
            'domain_result': {}
        },
        {
            'query': 'original Phrase',
            'channel': 'mp',
            'intent_result': {
                'entities': [
                    {
                        'entity': 'name5', 'type': 'type5', 'score': 0.88, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label5'
                    },
                    {
                        'entity': 'name6', 'type': 'type6', 'score': 0.78, 'start_index': 1, 'end_index': 2, 'canon': 'canon1', 'label': 'label6'
                    }
                ],
                'top_result': {'intent': 'intent.tv.search', 'score': 0.81},
                'intents': [
                    {'intent': 'intent.tv.search', 'score': 0.81},
                    {'intent': 'intent.tv.display', 'score': 0.75}
                ]
            },
            'domain_result': {}
        }
    ]
}

Aura – development

Docs:

Aura NLP Adapters

What are Aura NLP adapters

Description

Path

Files

Configuration

Intent Entity Mapper

Description

Path

Files

Best practices to edit intent_entity_mapper.json

Configuration

None Handler

Description

Path

Files

Configuration

Standard Threshold

Description

Path

Files

Configuration

Entity Tagger Adapter

Description

Path

Files

ner_entity_translation.json

ner_aliases.json

Best practices for the edition of ner_aliases.json

Configuration

Description

Path

Files

Configuration

Intent Disambiguation Adapter

Description

Intent disambiguation with a blacklist of intents

Path

Files

Configuration

Examples of intent disambiguation adapter

Length Adapter

Description

Path

Files

Configuration

Docs:

Aura Minibot user guide

Introduction to Aura minibot

Pre-requirements

Register a bot in Azure

Install and configure Aura minibot

Set all the required environment variables

Bot credentials

Access to the database

Run a local database

Run Aura minibot on docker

Get registry access

Pull minibot and minigroot images

Get all available versions from registry

Get latest version

Launch minibot

Work with Aura minibot and install new dialogs

Install Dialogs

Install a new dialog

Install an existing dialog

Run Aura minibot

Update a single dialog

Remove a Dialog

Working with Mocks in Aura minibot

Enable Custom Mocks

Disable Custom Mocks

Aura minibot start-up messages

Aura minigroot start-up messages

Test the bot

Create a Direct Line token

Publish your bot

Test from POSTMAN

Best practices to edit `intent_entity_mapper.json`