Aura – dialog

Docs:

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

account-linking dialog

Description of the account-linking dialog, one of the dialogs that handles users’ account linking

Introduction

The account-linking dialog is included in the global linking library.

It is in charge of handling user’s account linking for channels using integrated authentication, that is, channels that already have a proper user’s identifier that should be linked with the corresponding auraId and that cannot handle Kernel authentication directly:

WebClient
Facebook
WhatsApp

This dialog launches authentication in Kernel based on browser navigation. It includes several steps to validate the Terms and Conditions of the services and to launch the user’s autentication in the OB authenticator and in Kernel that, in the end, would register the auraId in Aura users’ database.

Environment variables

Property	Type	Scope	Description
LINKING_FP_ACCESS_SESSIONS_ENDPOINT	string	Local	URL to Kernel Access Sessions API
LINKING_FP_CALLBACK_LOGIN_URL	string	Local	URL to redirect to authentification login
LINKING_FP_CALLBACK_LOGOUT_URL	string	Local	URL to redirect to authentification logout
LINKING_TERMS_AND_CONDITIONS_URL	string	Local	URL to terms and conditions HTML file. By default: `/documents/termsandconditions.html`
SAFETY_CHECK_ENDPOINT	string	Local	URL API client endpoint

Docs:

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

Aura Bot main dialog

Description of the main dialog, one Aura Bot core dialog that maps the recognized intent with a specific dialog

Introduction

The main dialog is one of the aura-bot core dialogs in charge of routing from the recognized intention of the user to the specific dialog that provides the functionality required in an intended channel.

main dialog extends ComponentDialog, as all the rest of the dialogs. It is an internal dialog that contains all the intents-to-dialog routing map. It is loaded during the AuraBotserver start-up to be injected as a property in aura-bot and used after each intent recognition to execute the selected dialog.

At this stage, it is both instantiated and initialized, through these steps:

First, the whole list of plugins to be loaded in the system are passed to the dialog.
It also counts on the instance of the Aura BotFramework adapter, used during this start-up phase.
Then the WaterfallDialog with all the steps managed by the main dialog is added to the dialog.
After that, it is initialized:
- A RoutingMap is created.
- All the configured plugins are registered:
  - First of all, internal dialogs are included as dialogs: context-filter dialog and suggestions dialog.
  - Then, all the plugins configured in plugins-config are looped to add the routes of all their dialogs in the RoutingMap property of the main dialog, used during the activities processing to map the recognized intent to the corresponding dialog.

During the activity processing, the ActivityHandler calls MainDialog.run method to handle the incoming activity (in the form of a TurnContext), that passes it through the dialog system. If no dialog is active, it starts the default dialog. If there is any error in the TurnContext, the processing stops here and is sent to the channel.

At this stage, the main dialog is in charge of:

Routing the recognized intent to the dialog that handles it for the current channel.
Update Aura Context information of the current activity to include the dialog information.
If the dialog includes a contextFilter that fits the user’s context, then the dialog executed is the internal context-filter dialog.
If the user’s context does not match with the contextFilter of the dialog or the dialog does not have any contextFilter, then the next step of the main dialog is executed to validate if the Kernel accessToken of the user includes the scopes and purposes needed to execute the dialog.
- If the accessToken has no permissions to access it, then an error is returned, notifying the channel that the user has not consented aura-bot to access the specific API.
- If authorization is correct, then the specific dialog is executed.
When it ends, the next step of the main dialog is executed to check whether or not the dialog needs suggestions. If the dialog is configured to send suggestions and the user’s settings support them, then the internal SuggestionsDialog is executed.
When it ends, the main dialog also ends and an outgoing message flow is started.

Find here detailed information regarding the Routing Manager.

Docs:

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

Aura utils

Aura utils is an utility found in Aura Bot common library to manage dialogs and prompts

Introduction

Aura utils utility allows managing Aura dialogs and prompts.

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

It contains different methods, described in the following sections.

DialogUtils

Generic tools for any dialog.

setDataActiveDialog

It saves data between steps of a waterfall. Only valid in the same dialog.

param	type	description	mandatory
context	WaterfallStepContext	Context in a step of a Waterfall	yes
keyData	string	Key to recover data saved	yes
data	any	Data to be saved	yes

DialogUtils.setDataActiveDialog(stepContext, KEY_DESCRIPTION, description);

getDataActiveDialog

It gets data between the steps of a Waterfall through an identifier.

param	type	description	mandatory
context	WaterfallStepContext	Context in a step of a Waterfall	yes
keyData	string	Key to recover data saved	yes

const description = DialogUtils.getDataActiveDialog(stepContext, KEY_DESCRIPTION);

getResourcePath

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

param	type	description	mandatory
libraryName	string	Original file name, that was uploaded to the blob-storage.	yes
baseFilePath	string	Path in Azure Storage from library name (static-resources/libraries/library_name) to resource name.	yes
configuration	Configuration	Set of of configuration variables.	yes

const uriGenericRaw= DialogUtils.getResourcePath('generic', `${this.configuration.GENERIC_RESOURCES_BASE_PATH}/config/${this.configuration.GENERIC_RAW_NAME}`, this.configuration)

If we need a full URL image path including device resolution, getImageUrl method from @telefonica/aura-bot-library-util should be used instead.

isDeeplink

It returns true if the passed URL is a deeplink, and false otherwise.

param	type	description	mandatory
url	string	URL to check.	yes

const isDeepLink = DialogUtils.isDeeplink('http://movistar.es/campain/ahora.html')

PromptUtils

getRetriesValidator

It gets a validator function that will be called each time the user responds to the prompt. In this function, it controls the number of retries to show the prompt.

If attempt is allowed, it is the recognizer that will let an attempt (when there are not results) or the dialog the will manage the result found.

If the retries exceed to maxRetries parameter, the control will be returned to dialog, managing results or not.

If an attempt is shown, the configured retryPrompt (or the same prompt as default) will be shown.

param	type	description	mandatory
maxRetries	number	Number of retries to show the prompt	yes

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

getRetriesValidatorAndOverwriteRecognizerResult

This validator function is similar to getRetriesValidator but also overwrites the recognizer result obtained by the prompt recognizer with a previous stored value.

This recognizer result value can be set with the function ContextUtils.setPromptRecognizedResult. By default, the result is: prompt-check-recognizer-middleware.

param	type	description	mandatory
maxRetries	number	Number of retries to show the prompt	yes

// Create a ChoicePrompt with 3 retries and use of ordinals control overwriting promptRecognizedResult with the value of aura-bot.
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesValidatorAndOverwriteRecognizerResult(3));

getAbsolutePath

It returns an absolute normalized file path.

param	type	description	mandatory
filePath	string	File path to convert	yes

const path: string = getAbsolutePath('/test/demo_path.txt');

Docs:

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

Global authentication dialogs

Global authentication dialogs support different types of authentication in Aura

Global authentication dialogs include:

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

Aura Bot generic-ai-dialog-v1

Description of Aura bot generic-ai-dialog-v1, that allows managing several experiences for TV channels using AI services and complex logic resolution.

Introduction

The generic-ai-dialog-v1 allows OBs to implement search and recommendation use cases for TV channels based on AI services and complex logic resolution for channelData v1 channels.

You can check its source code in Github: generic-ai-dialog-v1.ts.

Environment variables

Property	Type	Description	Mandatory
AURA_AUTHORIZATION_HEADER	string	Authorization header to be sent to `AURA_GATEWAY_API_ENDPOINT`	yes
AURA_COMPLEX_LOGIC_ENDPOINT	string	URL of Complex Logic endpoint to interact with resolution API.	yes
AURA_GATEWAY_API_ENDPOINT	string	URL of Aura Gateway API endpoint	yes
AURA_GATEWAY_API_ISSUER_URL	string	Issuer URL for token info	yes
AURA_CHANNELDATA_DEFAULT_VERSION	string	Default version of channelData. By default `1.0.0`.	no
AURA_CHANNELDATA_LA_DEFAULT_VERSION	string	Default version of channelData for Latin America. By default `2.0.0`.	no
GENERIC_MP_RESOLUTION_NO_RESULT_CODE	string[]	List of resolution codes that indicate no results found. By default `['211', '462']`.	no

How it works

The dialog works in a similar way to the generic-ai-dialog-v3 but adapted to the structure of channelData v1.

Complex Logic proxy is used to interact with Complex Logic resolution API, which returns a response similar to Movistar Plus Resolution API. This adaptation is only valid for TVSearch responses for STB channel, because only a subset of fields has been mapped from normalized TV API to legacy TV API.

Docs:

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

Aura Bot generic-ai-dialog-v3

Description of Aura bot generic-ai-dialog-v3, that allows managing several experiences for TV channels using AI services and complex logic resolution.

Introduction

The generic-ai-dialog-v3 allows OBs to implement search and recommendation use cases for TV channels based on AI services and complex logic resolution for channelData v3 channels.

You can check its source code in Github: generic-ai-dialog-v3.ts.

Environment variables

Property	Type	Description	Mandatory
AURA_AUTHORIZATION_HEADER	string	Authorization header to be sent to `AURA_GATEWAY_API_ENDPOINT`	yes
AURA_COMPLEX_LOGIC_ENDPOINT	string	URL of Complex Logic endpoint to interact with resolution API.	yes
AURA_GATEWAY_API_ENDPOINT	string	URL of Aura Gateway API endpoint	yes
AURA_GATEWAY_API_ISSUER_URL	string	Issuer URL for token info	yes
AURA_CHANNELDATA_DEFAULT_VERSION	string	Default version of channelData. By default `1.0.0`.	no
AURA_CHANNELDATA_LA_DEFAULT_VERSION	string	Default version of channelData for Latin America. By default `2.0.0`.	no

Adding configurations for the AI Service

To use the AI Service, you need to add the intent configurations to the channel settings. The configurations should be added in the following format:

{
    "atria": {
        "dialogs": {
            "intent.tv.retrieve": {
                "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
                "presetId": "5d06f26c-a8d8-4f45-a999-102aaa8b191b"
            }
        }
    }
}

With this configuration, when the generic-ia-dialog-v3 is called with the intent intent.tv.retrieve, it will use the specified applicationId and presetId to call the generative API.

How it works

Steps

The dialog starts by retrieving the intent information from the context and logging the start of the dialog.
Then, it calls the AI service to get a generative response based on the intent and the current session ID. The session ID is updated in the context for future requests.
Next, it calls the complex logic service to get a resolution based on the intent and entities from the generative response.
If the resolution indicates no content found, it redirects to the conversational-search dialog.
Otherwise, it builds an activity to be sent to the user using the intent result, intent settings, and resolution.
If any error occurs during these steps, it logs the error, sets the error in the context, and builds an activity from the error.
Finally, it sends the activity to the user and ends the dialog.

Sequence diagram

sequenceDiagram
    autonumber
    participant User
    participant Dialog
    participant AI Services
    participant Complex Logic
    participant Conversational Search
    Dialog->>Dialog: Retrieve intent information from context
    Dialog->>AI Services: Call AI service with intent and session ID
    AI Services->>Dialog: Return generative response and session ID
    Dialog->>Complex Logic: Call complex logic service with intent and entities
    Complex Logic->>Dialog: Return resolution
    alt No content found in resolution
        Dialog->>Conversational Search: Redirect to conversational-search dialog
    else Content found
        Dialog->>Dialog: Build activity with intent result, intent settings, and resolution
        Dialog->>User: Send activity to user
    end
    Dialog->>Dialog: End dialog

Docs:

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

Aura Bot generic-dialog v1

Dialog based on a simple configuration that allows managing several experiences for TV channels. This version is compatible with channelData v1.

Introduction

The generic-dialog allows OBs to implement certain local use cases for Movistar Home, Movistar Plus and Set-top Box (STB) channels in an autonomous, agile and simple way with no code development, only by means of configuration.

Use this generic-dialog if your channelData version is v1.

You can check its source code in Github: generic-dialog.ts.

Included intents

The next table shows current intents available on generic-dialog and the previous library where the intent was set.

Intent	Previous library
intent.common.goodbyes	common
intent.common.greetings	common
intent.common.help	common
intent.common.swearwords	common
intent.common.thankyous	common
intent.communications.silent_mode_on	communications
intent.communications.silent_mode_off	communications
intent.communications.call_voicemail	communications
intent.communications.add_contact	communications
intent.communications.phone_pick_up	communications
intent.communications.call	communications
intent.communications.call_by_number	communications
intent.communications.call_by_name	communications
intent.communications.check_calls	communications
intent.communications.redial	communications
intent.communications.ignore_calls	communications
intent.domotics.light_on	domotics
intent.domotics.light_off	domotics
intent.ecommerce.add_to_wish_list	ecommerce
intent.miscellaneous.radio_turn_off	miscellaneous
intent.miscellaneous.time_check	miscellaneous
intent.miscellaneous.weather_forecast	miscellaneous
intent.miscellaneous.news_listen	miscellaneous
intent.navigation.section_show	navigation
intent.navigation.back	navigation
intent.navigation.next	navigation
intent.navigation.previous	navigation
intent.carousel.info	tv
intent.tv.details	tv
intent.tv.help	tv
intent.tv.init	tv
intent.tv.from_beginning	tv
intent.tv.record	tv
intent.tv.channel_down	tv
intent.tv.channel_up	tv
intent.tv.move_backwards	tv
intent.tv.move_forwards	tv
intent.tv.mute	tv
intent.tv.unmute	tv
intent.tv.stop	tv
intent.tv.off	tv
intent.tv.on	tv
intent.tv.pause	tv
intent.tv.resume	tv
intent.tv.volume_down	tv
intent.tv.volume_up	tv
intent.tv.c2c	tv
intent.tv.content_get_info	tv
intent.tv.none	tv
intent.tv.question_time_loc	tv
intent.tv.search	tv
intent.tv.search_similar	tv
intent.tv.vod_epq_information	tv
intent.tv.watching_now	tv
intent.tv.suggestions	tv
intent.wifi.get_access	wifi

Generic indexed text

Generic dialog implements an algorithm, which based on a dialog configuration, can customize its response. The getIndexedText function returns a POEditor resource based on the dialog configuration’s setting indexedResourceBase and the value entity.entity obtained from the first entity. This functionality relies in those two values and will return an error if they are not present.

{
    "intent": "intent.exact-match.faq",
    "settings": {
        "indexedResourceBase": "generic:faq-answer.",
        "functions": {
            "params": [
                "context",
                "currentIntent",
                "persistentData"
            ],
            "algorithm": "getIndexedText"
        }
    }
}

In this example, the reference that will be searched in POEditor will be generic:faq-answer.X, where X is the identifier gathered from the first entity.

Keep in mind that in function.params there has to be an array of parameters that will be used in getIndexedText.

Enabling AI resolution

To enable the AI-based fallback mechanism, add the flag enableAIResolution to true inside the dialog configuration for the intent. This setting allows the dialog to use the ai recognizer when the NLP resolution returns no entities or when the Movistar Plus resolution returns no results.

Example configuration:

{
    "intent": "intent.tv.search",
    "settings": {
        "locales": {
            "error": [
                "core:flc.answer.error"
            ]
        },
        "enableAIResolution": true,
        "needTvResolution": true
    }
}

AI fallback resolution

When using generic-dialog v1 and needTvResolution is set to true, a fallback mechanism using AI services is available if enableAIResolution is set to true in the dialog configuration.

If NLP resolution returns no entities or when the Movistar Plus resolution returns no results, the system applies an AI-based fallback strategy (“triage”). This ensures robustness and continuity of the dialog flow.

The fallback is triggered in two scenarios:

No entities detected If the intent requires TV resolution and no entities are returned by the NLP (intentResult.entities?.length === 0), the dialog calls the recognizeUsingAI function. If a new intent is successfully recognized, the current dialog is replaced by the new one.
Movistar Plus resolution returns no results When the intent and entities are passed to Movistar Plus Resolution but no valid result is obtained (GENERIC_MP_RESOLUTION_NO_RESULT_CODE), the system again invokes recognizeUsingAI. A new intent will be attempted and, if available, the dialog is redirected accordingly.

In both cases, the interaction origin is marked as InteractionOriginType.NoResults.

Docs:

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

Aura Bot generic-dialog-v3

Dialog based on a simple configuration that allows managing several experiences for TV channels. This version is compatible with channelData v3.

Introduction

The generic-dialog-v3 allows OBs to implement certain local use cases for channelData v3 channels in an autonomous, agile and simple way with no code development, only by means of configuration.

You can check its source code in Github: generic-v3-dialog.ts.

Differences between generic dialog v1 and v3

These are the main differences in comparison with the generic-dialog v1:

Deprecated fields in dialog’s settings (dialogLibraries.dialogs.triggerConditions.settings):
- type, action, payload, addEntitiesToPayload, sound, payloadType and isFullScreen are no longer used.
- action, payload and sound configurations will be transformed to the new actions format and added to the new field actions.
New field actions: This field contains the configuration of all the actions returned inside the channelData.

Generic dialog environment variables

Generic

Property	Type	Scope	Description
TV_VOLUME_LEVELS_UP_DOWN	number	Local	Number of points at which the volume can be raised and lowered. By default `5`.
TV_MOVE_SECONDS_BACKWARD_FORWARD	number	Local	Number of seconds in which user can forward or rewind a video. By default `60`.
WIFI_FP_SMART_WIFI_ENDPOINT	string	Local	URL Kernel endpoint endpoint to interact with smart wifi API.
TV_TIMER_RECOGNIZER_FIRST_ENTITY_CONFIG	string	Local	Configuration of the recognition of entities with timer content in first position to calculate number of seconds. By default: `1 4:0.25,3 4s:0.75,4 de hora:0.25,hora:1.0,media:0.5,medio:0.5,minuto:1.0,un:1.0,un 4:0.25,una:1.0`.

| TV_TIMER_RECOGNIZER_SECOND_ENTITY_CONFIG | string | Local | Configuration of recognition of entities with timer content in second position to calculate number of seconds. By default: 1 4:0.25,3 4s:0.75,4 de hora:0.25,hora:1.0,media:0.5,medio:0.5,minuto:1.0,un:1.0,un 4:0.25,una:1.0,4:0.25. |

Generic dialog utilities

There are several functions that implement different requirements for the generic-dialog such as:

calculateSecondLevels: Calculate the value in seconds in case the entity type is not expressed in this format: ent.time_length_sec. Right now it only converts minutes into seconds.
getIndexedText: Get the text’s reference with information about the entity value.
getInfoWifiPlus: Retrieve Wi-Fi info.
getSecondsLevelsWithTimerRecognizer: Calculates the total number of seconds, based on the provided timer entities, making a recognition and conversion of them depending on the configuration of each country. The configuration is added in the environment variables: TV_TIMER_RECOGNIZER_FIRST_ENTITY_CONFIG and TV_TIMER_RECOGNIZER_SECOND_ENTITY_CONFIG.
getWifiInfo: Manage Wi-Fi data by setting the persistentData and the value of movistarPlusResolution.

AI fallback resolution

The configuration and fallback mechanism for AI resolution in generic-dialog-v3 are the same as in generic-dialog v1.

The only difference is in the second fallback condition:

In generic-dialog v1, the fallback is triggered when Movistar Plus resolution returns no results.
In generic-dialog v3, the fallback is triggered when the complex logic resolution process returns no results.

All other aspects (configuration with enableAIResolution, marking the interaction origin as InteractionOriginType.NoResults, and redirecting to the new dialog) remain exactly the same.

Docs:

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

Description of Aura bot conversational-search-dialog, that is specifically designed to resolve the advanced TV recommendation using LLMs in ATRIA and complex logic resolution.

Introduction

The conversational-search-dialog is specifically designed to resolve the advanced recommendation, using LLMs in ATRIA. Specifically the LLM configured for TV Conversational Search UC.

You can check its source code in Github:

conversational-search-dialog.ts.
conversational-search-v3-dialog.ts. Currently, this dialog is available for Aura channelData V1 and V3 versions.

For this use case, the required specific configuration is set below:

{
            "channelDataVersion": "v3", // Only in Aura channelData V3 version
            "id": "conversational-search-dialog-v3",
            "allowAnonymous": true,
            "triggerConditions": [
                {
                    "intent": "intent.conversational.search",
                    "settings": {
                        "locales": {
                            "error": [
                                "core:flc.answer.error"
                            ]
                        },
                        "needTvResolution": true
                    }
                }
            ],
            "bypass": {
                "duration": 60,
                "payloadName": "openai",
                "initialData": {},
                "recognizersEnabled": true,
                "recognizersBreakIntents": {
                    "intent.tv.display": [],
                    "intent.navigation.section_show": []
                }
            }
        }

Specific values

Key	Value	Description
bypass.duration	60 (minutes)	This value overwrites the default aura-bot value for bypass lasting 10 minutes.
bypass.payloadName	openai	Name of the interface that will be used as bypass payload for this dialog.
bypass.initialData	empty	It should contain any data needed by the dialog to be initialized.
bypass.recognizersEnabled	true	This value overwrites the default aura-bot way of working with recognizers when it is in bypass mode. If it is set to `true`, recognizers are executed, and their result is stored in the bypass payload to be used, if needed, afterwards.
bypass.recognizersBreakIntents	Array of intents	Used to handle when the user requested any other use case during the execution of the TV Conversational Search UC.

Configuration by channel

For this dialog it is necessary to add the configuration of applicationId and presetId per channel and intent in the channel model.

For this use case, the required specific configuration per channel is set below:

{   
    "atria": {
        "dialogs": {
            "intent.conversational.search": {
                "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
                "presetId": "acdef02f-f810-4474-8143-6b2a04a042f8"
            }
        }
    }
}

Environment variables

Property	Type	Description	Mandatory
AURA_AUTHORIZATION_HEADER	string	Authorization header to be sent to `AURA_GATEWAY_API_ENDPOINT`	yes
AURA_COMPLEX_LOGIC_ENDPOINT	string	URL of Complex Logic endpoint to interact with resolution API.	yes
AURA_GATEWAY_API_ENDPOINT	string	URL of Aura Gateway API endpoint	yes
AURA_GATEWAY_API_ISSUER_URL	string	Issuer URL for token info	yes
AURA_CHANNELDATA_DEFAULT_VERSION	string	Default version of channelData. By default `1.0.0`.	no
AURA_CHANNELDATA_LA_DEFAULT_VERSION	string	Default version of channelData for Latin America. By default `2.0.0`.	no
CONVERSATIONAL_SEARCH_MAX_TAGS	number	Default number of max tags to manage in the dialog. By default `4`.	no
CONVERSATIONAL_SEARCH_TAGS_SCORE_THRESHOLD	number	Default number with minimum score threshold required for a tag to be considered relevant in a TV Conversational Search. Value of this variable oscillates between 0 and 1. By default `0`.	no

How it works

Steps

The dialog starts by init bypass mode.
Then, it checks if the iteration comes from the Triage recognizer, by setting the user’s text to the fixed phase of resource: tv-conversational-search:command.recommend and then calling the AI service.
If the iteration originated because there were no results, it will return the text obtained from the resource: tv-conversational-search:command.no-results to the user.
Then, it calls the AI service to get a generative response based on the intent and the current session ID. The session ID is updated in the context for future requests.
Next, with the response obtained from the LLM, the user will be composed of the following:
- If the generative response returns command info, It will be checked if the command is EXIT so the bypass will be closed and the resource: tv-conversational-search:command.exit will be returned to the user.
- If the generative response returns tags info, it calls the complex logic service to get a resolution based on the intent and tags from the generative response. If the tags are not valid or not meet a threshold or there are no results, the resource will be returned: tv-conversational-search:command.no-results. Instead, ff content exists, it will be returned in the channel data, but the text of the result shown to the user will always be the one obtained from generative response.
- If the generative response returns text info, this text is included in response of user, unless there are no results, as we indicated in the previous paragraph, a specific resource will be returned.
Finally, it sends the activity to the user and ends the dialog.
The bypass will only be closed if these two conditions are met:
- The ‘EXIT’ command is detected.
- A new user intent configured that match those configured in the dialog in field: recognizersBreakIntents.

Sequence diagram

sequenceDiagram
    autonumber
    participant User
    participant Dialog
    participant AI Services
    participant Complex Logic

    Dialog->>Dialog: Open dialog 
    Dialog->>Dialog: Init bypass mode and check interaction origin
    alt interaction origin is no-results
        Dialog->>User: Send activity to user with command no-results text
        Dialog->>Dialog: End dialog
    else interaction origin is triage
        Dialog->>Dialog: set text to send LLM with command recommend.
    end
    Dialog->>Dialog: continue bypass
    alt user intent recognized match with break intent configured
        Dialog->>Dialog: Close bypass
        Dialog->>User: Send activity to user with command exit text
    else user intent is not break intent configured
        Dialog->>Dialog: continue bypass
        Dialog->>AI Services: Call AI service with intent and session ID
        AI Services->>Dialog: Return generative response and session ID
        alt generative response contains a 'EXIT' command
            Dialog->>Dialog: Close bypass
            Dialog->>User: Send activity to user with command exit text
            Dialog->>Dialog: End dialog
        else generative response contains tags
            alt tags are valid
                Dialog->>Complex Logic: Call complex logic service with intent and tags
                Complex Logic->>Dialog: Return resolution
                alt No content found in resolution
                    Dialog->>User: Send activity to user with command no-results text
                else Content found
                    Dialog->>User: Send activity to user with text of generative response and resolution
                end
            else tags are invalid
                Dialog->>User: Send activity to user with command no-results text
            end
        else generative response contains text
                Dialog->>User: Send activity to user with text of generative response
        end
    end
    Dialog->>Dialog: End dialog

Docs:

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

Aura Bot core dialogs

Aura Bot core dialogs are internal global dialogs that are deployed within a specific Aura Platform release

Introduction

The following aura-bot core dialogs are global ones designed and developed by Aura Platform Team that are at the OBs’ disposal to build experiences in Aura. OBs cannot modify their logic but use them as they are.

These dialogs are deployed jointly with the corresponding Aura Platform release.

As intended for Aura global experiences, they are named below but fully described in the section Global use cases together with other global dialogs.

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

context-filter dialog

Description of the global context-filter dialog that manages contextFilters to configure the behavior of a specific dialog.

Introduction

ℹ️ The context-filter dialog is an aura-bot core dialog, deployed jointly with the corresponding Aura Platform release.

Find the source code of this dialog in its different versions:

If your channelData version is v1, then use context-filter.ts
If your channelData version is v3, then use context-filter-v3.ts

The context-filter dialog handles the execution of all the contextFilters configured in each dialog, evaluating all the properties of the contextFilter, within the triggerCondition model.

Does the current contextFilter break the dialog execution? If breakDialogExecution is true, then the response to the request is just handled by the contextFilter, as the dialog is not executed.
Does the current contextFilter break the rest of the contextFilters evaluation? If breakFilterEval is true, then the rest of the configured contextFilters are not evaluated.
resource: if the contextFilter condition is matched, then the configured resource is returned to the user.
redirectToIntent: if the contextFilter condition is matched, then the execution passes to the dialog in charge of the configured intent for the current channel.
suggestions: flag to indicate whether or not the response handled by the contextFilter should return suggestions to the user.

Example: Scenario 1

Couple of contextFilter, both of them break the dialog execution and only return a resource.
None of them break the rest of the contextFilter evaluation, so the last matching contextFilter resource is returned.

In this case, if the user is prepaid, the response is bill:bill.check.prepaid with suggestions; if the user is multimisdn, the response is context-filter:multimsisdn-users-intent-not-allowed.text without suggestions. It works the same than setting breakFilterEval to true, what it is in fact recommended, to avoid performance loss.

"triggerConditions": [
                {
                    "intent": "intent.billing.check",
                    "contextFilters": [
                        {
                            "name": "subscription_type_prepaid_invoice",
                            "type": "subscription_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
                            }
                        },
{
                            "name": "Multimsisdn Not Allowed",
                            "type": "UserType",
                            "conditions": "/type eq 'multimsisdn'",
                            "true": {
                                "name": "Return_resource_not_multimsisdn_allowed",
                                "breakDialogExecution": true,
                                "breakFilterEval": false,
                                "resource": "context-filter:multimsisdn-users-intent-not-allowed.text",
                                "suggestions": false
                            }
                        }

]

Example: Scenario 2

Single filter configured, that matches whether the user is anonymous or not. If the user is anonymous, then the dialog execution is broken and the rest of the contextFilter are not evaluated. The execution is redirected to the dialog that handles intent.account.linking for the current channel.
Redirect to the dialog indicated in the contextFilter of the dialog settings:

"contextFilters": [
        {
            "name": "Anonymous redirect to linking",
            "type": "type",
            "conditions": "/type eq 'anonymous'",
            "true": {
                "name": "Anonymous redirect to linking",
                "breakDialogExecution": true,
                "breakFilterEval": true,
                "redirectToIntent": "intent.account.linking",
                "suggestions": false
            }
        }
    ]

Docs:

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

Template for Aura Bot dialogs testing

Template for testing an Aura Bot dialog

Template


import 'mocha';
import { TestAdapter, ConversationState, MemoryStorage, UserState } from 'botbuilder';
import { DialogTurnStatus, DialogSet } from 'botbuilder-dialogs';
import { AddBillDialog } from '../dialogs/collections/bill/add-bill';
import { AuraDataAccesor } from '../models';

describe('Dialog Test', function () {
    this.timeout(5000);
    /**
     * The dialog template test.
     */
    it('Bill dialog Test', (done) => {
        /**
         * Set the common data of Aura-Bot
         */
        const testData = setCommonData();
        /**
         * Uset TestAdapter to launch the bot framework
         */
        const adapter = new TestAdapter(async (turnContext) => {
            const dc = await dialogs.createContext(turnContext);
            const results = await dc.continueDialog();
            if (results.status === DialogTurnStatus.empty) {
                await dc.beginDialog('addBill');
            }
            await testData.conversationState.saveChanges(turnContext);
        });
        /**
         * Create the dialog set and add dialogs to test
         */
        const dialogs = new DialogSet(testData.auraDataAccesor.dialogState);
        dialogs.add(new AddBillDialog(testData.auraDataAccesor));
        /**
         * Make a flow with sends and assert responses
         */
        adapter.send('Hello')
            .assertReply('Dime algo bonito')
            .send('Algo bonito')
            .assertReply('Gracias por el piropo')
            .assertReply('Please enter your name. (1) Yes or (2) No')
            .send('claro')
            .assertReply('end Yes')
            .then(() => done())
            .catch((err) => done(err)); // <- send error to done
    });
});

/**
 * Common Data uses by the Aura Bot.
 */
function setCommonData() {
    const memoryStorage = new MemoryStorage();
    const conversationState = new ConversationState(memoryStorage);
    const auraDataAccesor: AuraDataAccesor = {
        conversationData: conversationState.createProperty('conversationData'),
        userData: new UserState(memoryStorage).createProperty('userData'),
        dialogState: conversationState.createProperty('DialogState')
    };
    return {
        auraDataAccesor,
        conversationState
    };

}

Docs:

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

Aura bot generic-ai-dialog

Description of Aura bot generic-ai-dialog, that allows managing several experiences for TV channels using AI services and complex logic resolution.

Introduction

The aura-bot-generic-ai-library library includes the following list of dialogs:

generic-ai-dialog-v1: allows managing several experiences for TV channels using AI services and complex logic resolution for channelData v1 channels.
generic-ai-dialog-v3: allows managing several experiences for TV channels using AI services and complex logic resolution for channelData v3 channels.

Docs:

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

Aura bot generic-dialog

Description of Aura bot generic-dialog, that allows managing several experiences for TV channels based on a simple configuration

Find here details regarding the global generic library and dialogs’ versions and the condition for a use case to be generic

Introduction

Different versions compatible with channelData v1 and v3 are available:

If your channelData version is v1, then use generic-dialog-v1
If your channelData version is v3, then use generic-dialog-v3

Aura global generic-dialog

The generic-dialog responds to the intention of having a single dialog based on configuration that allows managing several intents whose behavior is similar.

Therefore, it allows the development of certain types of use cases in a simple and autonomous way, with no associated code development and simply by means of configuration.

The global generic-dialog file, generic-dialog.ts includes the logic for the use case execution, where configuration is recovered and the output message is generated with the defined parameters.

Besides this global generic-dialog, there are several plugins based on the same dialog, all of them working as the global one and with similar code. In this framework, each OB have a specific generic-dialog in its corresponding library generic-[OB]/ which must be used when developing a local use case.

The global library that includes the generic dialog is named generic and has been designed for the management of different types of dialogs.

You can find it here.

Conditions for a use case to be generic

In order to consider a use case as part of the generic-dialog, it must fulfil these conditions:

✅ Local use cases developed from scratch by the OBs.
✅ Use cases with intents that can be managed by Movistar Plus, Movistar Home or Set-Top-Box (STB) channels.
✅ Dialog with only one interaction with the user: only one message from the user and one response from the bot are allowed. For example: greetings dialog.
✅ There is a direct transformation from intent to action (you may or may not call the API Movistar Resolution for this purpose). For example: tv-remote-actions use cases).
✅ Use cases that require the conversion of input parameters through a function to get the correct payload. For example: conversion on entities. For example: move_forward.
✅ Currently, only one text response is allowed:

settings.locale.success when all works fine.
settings.locale.error when something goes wrong.
Also, the text can be set in the response from the resolution API but, if required for example a variable text depending on the response of the API or the recognized entity, then developers must create another dialog.

Merely as examples of the potential of aura-bot generic dialog, below you can find different use cases for the channels Movistar Plus, Movistar Home or STB channels that can be developed through it. Use them as a reference for developing your own local experiences!

Docs:

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

get-oauth-url dialog

Description of the get-oauth-url dialog, one of the dialogs that handles users’ account linking

The get-oauth-url dialog is included in the global linking library.

This dialog returns to the channel the oauth URL to launch the account linking.

Docs:

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

account-remove dialog

Description of the account-remove dialog, one of the dialogs that handles users’ account linking

The account-remove dialog is included in the global linking library.

This dialog launches the logout process in Kernel based on browser navigation.

It includes several steps to remove the login session from Kernel and in the OB authenticator that, in the end, would remove the auraId from the Aura Users’ database.

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

Aura Bot dialogs

Description of Aura Bot dialogs, components in charge of the conversational flow with the users, its role in the bot and the different types of dialogs in Aura

Introduction

Dialogs are aura-bot components in charge of the use cases’ logic for establishing a conversational flow with the user and, if required, summoning Kernel or third-party APIs in order to fetch specific data and provide an appropriate response back to the user.

aura-bot dialogs are integrated into a library, which is a node.js package with a particular structure that can contain one or several dialogs plus i18n strings, environment variables, configuration files and graphical resources. Libraries are deployed in the bot as plugins.

Currently, aura-bot supports the Microsoft Bot Framework SDK v4 for JavaScript as the internal bot engine. For the dialogs development over aura-bot, developers are kindly requested to read the Microsoft documentation Send and receive text message.

Types of Aura Bot dialogs

aura-bot contains different types of dialogs:

Main dialog: dialog in charge of routing from the recognized intent to its specific dialog. Find detailed information here.
Core dialogs: the current core dialogs are described here.
Dialogs from global libraries that include the logic of Aura global use cases.

Local dialogs: Moreover, in the case of local experiences, which are developed by the OBs from scratch or inspired in global use cases, it is required to build a new local dialog with the logic of the use case. Learn how to build an Aura bot dialog.

Docs:

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

Configure Aura Bot in bypass mode

Orderly steps for the configuration of Aura Bot in bypass mode

Introduction

The main functionality of bypass mode, is that once we are in this mode within a conversation, any input message to aura-bot will be directly sent to the external service. Likewise, any message from the external service will be shown to the user without going through the bot recognition system.

In section bypass-mode-middleware you can find detailed information regarding the middleware that manages the bypass mode and the bypass mode model.

How to configure Aura Bot in bypass mode

The configuration of aura-bot in bypass mode implies three steps that are shown below.

Initialize bypass mode

To use bypass mode, the dialog must initialize the bypass object.

Params Bypass.initialize method:

Property	Description
BypassState	Current bypass state
context	Current context of dialog
duration	Bypass life time in minutes
initialData	Initial data of bypass
payloadName	Name of the property in the `channelData.payload` used to send data to `bypass.ex: 'handover'`. For asynchronous APIs, it must be `asyncCallback`.
closeString	Comma-separated string or array of string with the words that directly close the bypass

    const bypass: Bypass<BypassModelData> = await Bypass.initialize(
            stepContext.context,
            this.timeout,
            {},
            'handover',
            BypassState.Init,
            getLiteral(stepContext?.context)('factotum:bypass.close.words'));

Once the bypass mode is initialized, all user’s messages will be redirected to the dialog. In bypass mode, when the dialog finishes all the actions of the use case logic, the dialog must be closed.

    return await stepContext.endDialog();

Execute bypass mode

Bypass information can be loaded into the dialog by calling the Bypass.loadBypass method.

    const bypass = await Bypass.loadBypass(stepContext.context);

From its initialization, the dialog should monitor the status of the bypass that can be one of the following:

BypassState.Off
BypassState.Init
BypassState.Bypass
BypassState.Closed

    const bypass = await Bypass.loadBypass(stepContext.context);
    switch (bypass.state) {
        case BypassState.Off:
        case BypassState.Init: {
            .....
            break;
        }
        case BypassState.Bypass: {
            ....
            break;
        }
        case BypassState.Closed: {
            ....
            break;
        }
    }

Bypass data field is used to exchange information between bypass interations, it is an any object. To update the information in the bypass object, the bypass object is modified to invoke updateBypass.

    const bypass = await Bypass.loadBypass(stepContext.context);
    bypass.data.value = bypass.data.value + stepContext.context.activity.text + ' ';
    await bypass.updateBypass(stepContext.context, false);

Close bypass mode

At any time the dialog can close the bypass mode by using the Bypass.closeBypass method.

    await Bypass.closeBypass(stepContext.context);

The bypass may also be closed because of its expiration or because the user has said any of the closing words. In these cases, when the control returns to the dialog, the state of the bypass will change to BypassState.Closed and the closeReason field will indicate the reason for the closing.

Example of dialog with Aura Bot in bypass mode

    export default class AuraBotTestBypass extends ComponentDialog {
    /**
     * Dialog id for the base Aura Bot app dialog.
     */
    public static readonly id: string = 'test-bypass';
    public TTL_BYPASS_MIN: number = 0.25; // 15 seconds
    /**
     * logger
     */
    public readonly logger = new AuraLogger.AuraBusEmitter('AuraTestBypass');
    public readonly autoRegister: boolean = true;
    protected configuration: Configuration;
    /**
     * Constructor for Bypass Handover.
     *
     * @param {Configuration} configuration The configuration joi schema.
     */
    constructor(configuration: Configuration) {
        super(AuraBotTestBypass.id);
        super.initialDialogId = AuraBotTestBypass.id;
        this.configuration = configuration;
        super.addDialog(new WaterfallDialog(AuraBotTestBypass.id, [
            this.handoverStart.bind(this),
            this.handoverContinue.bind(this)
        ]));
    }
    /**
     * Check Bypass Status
     * INIT: Start Bypass Mode and create Bypass model into userData.
     * BYPASS: Execute handoverContinue step dialog.
     * CLOSE: Remove Bypass Model from userData and close Dialog.
     *
     * @param {WaterfallStepContext} stepContext The current step context.
     */
    private async handoverStart(stepContext: WaterfallStepContext): Promise<DialogTurnResult> {
        const corr = ContextUtils.getCorrelator(stepContext.context);
        try {
            let bypass = await Bypass.loadBypass(stepContext.context);
            switch (bypass.state) {
                case BypassState.Off:
                case BypassState.Init:
                    bypass = await Bypass.initialize(stepContext.context, this.TTL_BYPASS_MIN, { value: '' }, 'test', BypassState.Bypass, ['exit','disconnect','disable']);
                    this.logger.info({ msg: `Bypass for: ${bypass.intent.intent} initialized`, corr });
                    await stepContext.context.sendActivity('Welcome to the CONCATENATOR, type "exit" to finish.');
                    return await stepContext.endDialog();
                case BypassState.Bypass:
                    this.logger.info({ msg: `Bypass for: ${bypass.intent.intent} continue`, corr });
                    return await stepContext.next(bypass);
                case BypassState.Closed:
                    await Bypass.closeBypass(stepContext.context);
                    this.logger.info({ msg: `Bypass for: ${bypass.intent.intent} closed`, corr });
                    if (bypass.closeReason === BypassCloseReason.BypassExpired) {
                        await stepContext.context.sendActivity('The CONCATENATOR has expired!');
                    }
                    await stepContext.context.sendActivity('The final result was: [ ' + bypass.data.value + ']');
                    return await stepContext.endDialog();
            }
        } catch (reason) {
            this.logger.error({
                corr,
                msg: 'Error handover bypass',
                error: reason.message,
                stck: reason.stack
            });
            await stepContext.context.sendActivity(reason.message);
            return await stepContext.endDialog();
        }
    }
    /**
     * Executes the logic for Bypass
     *
     * @param {WaterfallStepContext} stepContext The current step context.
     */
    private async handoverContinue(stepContext: WaterfallStepContext ): Promise<DialogTurnResult> {
        const bypass = stepContext.result;
        bypass.data.value = bypass.data.value + stepContext.context.activity.text + ' ';
        await bypass.updateBypass(stepContext.context, false);
        await stepContext.context.sendActivity(bypass.data.value);
        return await stepContext.endDialog();
    }
}

How to use prompts in bypass mode

Prompts can be used within a dialog working in bypass mode.

    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 is initialized.

    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 and the returned value can be collected 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();
    }

Docs:

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

seamless-account-remove dialog

Description of the seamless-account-remove dialog, one of the dialogs that handles users’ account linking

The seamless-account-remove dialog is included in the global linking library.

This dialog launches seamless logout in Kernel.

It counts on several steps to remove the login session from Kernel and in the OB authenticator that, in the end, would remove the auraId from the Aura users’ database.

Docs:

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

Test an Aura Bot dialog

Guidelines for the design and execution of unit tests for the validation of an Aura Bot dialog

Introduction

When developing a use case, and once the use case dialog is built, it is required to test the dialog in order to verify its proper performance in terms of the conversational flow between the user and aura-bot . This step is mandatory for the OB developers in order to merge their Pull Requests.

This task comprises three main steps:

Generate the unit tests and place them on the use case library.
Execute the unit tests through the Test Adapter that simulates sending messages from the user to the bot.
Validate the dialog with the unit tests within an iterative process: if results are not satisfactory, the required modifications must be done in the dialog .ts file.

Generate the unit tests files

Within the use case library, it is recommended that the unit tests files are placed in the folder src/ folder.
They should be named with the same name as the correponding dialog, which must be also included in this folder:
Dialog: <dialog-name>.ts ➡ Test file: <dialog-name>.spec.ts
Moreover, if auxiliary files are required for the tests, they can be optionally placed in a folder named /test.

📌 For a proper understanding of the unit tests for dialogs, it is recommended that developers check the source code of the Aura dialog greetings from the library common and its associated unit tests, as an example. The code of these unit tests can be also used as a template for designing your own tests.

Execute the Aura Bot dialogs unit tests

For the execution of the unit tests, read the guidelines How to debug with mocha and Typescript.

Docs:

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

Aura global dialogs: miscellaneous

Aura Global dialogs belonging to different fields of application in terms of users’ experiences

Introduction

This section includes both global dialogs/libraries that can be installed by the OB as well as core dialogs that are deployed within the corresponding Aura Platform release:

context-filter dialog in charge of all the contextFilters configured in each dialog.
disambiguation library in charge of disambiguation processes.
handover-genesys dialogs, available in the Whatsapp channel to handle handover experiences.
mocks-v3 dialog, in charge of returning mocked responses in channelData v3 format.
suggestions dialog that manages suggestions sent to the users.
unexpected-file dialog that controls the unforeseen files received in aura-bot.

Docs:

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

onboarding-whatsapp dialog

Description of the global onboarding-whatsapp dialog for WhatsApp channel

Introduction

The onboarding-whatsapp dialog is a simple dialog that returns some personalized messages for WhatsApp or other channel.

The dialog returns three messages with all the information necessary for the user’s onboarding and the Terms and Conditions acceptance.

According to the type of user (authenticated or anonymous), the messages will be different:

For anonymous users, the messages returned will be:

onboarding:onboarding.welcome
onboarding:onboarding.privacy
onboarding:onboarding.terms-and-conditions

For authenticated users, the returned messages will be:

onboarding:onboarding.auth.welcome
onboarding:onboarding.auth.privacy
onboarding:onboarding.auth.terms-and-conditions

If one of these texts are filled with " " in the locales, this message will not be sent, excepting terms-and-conditions text, which is mandatory. The first two messages, welcome and privacy, are only sent the first time this user arrives to the dialog. In succeeding interactions, only terms-and-conditions message will be returned.

Terms and conditions

aura-bot redirects to this dialog when Terms and Conditions settings are set, and the user has not accepted them yet.

More info about Terms and Conditions settings and flows here.

Docs:

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

Aura Global use cases

Discover the Global use cases developed by Aura Platform Team and put at the OB’s disposal and the global libraries and dialogs that contain the logic for different experiences

Aura Virtual Assistant components

Introduction

Global use cases are experiences already designed, developed and tested by Aura Platform Team.

OBs cannot modify their logic but use them as they are or get inspired for deploying their own experiences.

The current section includes:

Global dialogs / libraries, that contain the logic for the management of different experiences:
- Authentication dialogs, that manage different types of authentication in Aura.
- generic-ai-dialogs that allow managing several experiences for TV channels using AI services and complex logic resolution.
- generic-dialog that, currently, allows the implementation of certain experiences in TV channels.
- Other global dialogs grouped as miscellaneous.
Global use cases, as experiences that reach the final users:
Aura video use cases, that provide different experiences for Telefónica customers related to video services.
Use cases for testing Aura: libraries used by Aura Global Team for testing Aura Platform functionalities.

📃 Find guidelines for installing and using global experiences in your Aura system: Use global use cases.

ℹ️ With the introduction of the channelData normalized version (v3), these global dialogs will be progressively adapted to be compatible with this version. This information is included in the documentation of the specific dialogs where two versions (v1 and v3) are already available, together with the changes in the dialogs’ functionality that, for example, affect to video use cases.

Libraries configuration

aura-bot has the control to prepare and manage all configuration variables and make validations to get ready. In case that any validation fails, the set of libraries wrongly loaded will be shown and the bot will not start. If there is a problem with the scheme of an external library, the broken library should be extracted or fixed.

In order to validate schemas of the variables used in external libraries, it is optional that each library has an accessible scheme with the names of THEIR variables, default values, etc.

For example, there is a library that exposes a variable that contains a threshold that can be modified from outside that library. The developer´s library should create a schema (using @hapi/joi) specifying the name of the variable with the prefix of the library name (for example: LIBRARYNAME_THRESHOLD).

It is suggested that at the library level and within the src/ folder, a file named configuration-schema.ts is created, containing the configuration scheme like the one shown below:

import * as joi from 'joi';


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

export default configurationSchema;

In this first approach, there is no name validation (checking the prefix name of the variables).

Nomenclature for libraries variables

The naming of local library environment variables must follow these instructions:

Follow the structure: LIBRARYNAME_*.
If the environment variable is an endpoint: LIBRARYNAME_*_ENDPOINT.
If the environment variable is a Kernel endpoint: AURA_FP_*_ENDPOINT.
If the environment variable is a Kernel endpoint and is only used in one library or the use case uses a different API version than the global one: LIBRARYNAME_FP_*_ENDPOINT

Each library in this section includes its own variables.

Docs:

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

Build an operation in a developed dialog

Guidelines for building an operation within an already developed dialog.

Introduction

Besides first-level intents in Aura, that are associated to the execution of a dialog and have the following format: intent.[intent_name], there is another type of intents called Operations that do not have to be associated to a dialog.

An operation is an intention that makes sense within a context, that is, within a specific dialog conversational flow and when the dialog is waiting for an interaction with the user.

Operations are not recognized by Aura NLP but through a direct auraCommand or through a dialogContext.

Operations have the following format: operation.[operation_name].

How to build an operation

It is recommended to build a specific .ts file for each operation and place it in the following folder together with the use case dialogs’ files:
[repository_name]/src/ or [repository_name]/[library name]/src/

An example is shown below: If we want to select the seat for a flight and we say to Aura: “I want the seat 24A”. Then, the recognizer will choose an intention, but this intention only makes sense if it is within a sub-process, which in this case would be “buying tickets”. In the following example, we have already opened a session in Air Europe and we have sent the intention to buy tickets:

{
  "intent": "intent.air-europe.buy-ticket",
  "entities": []
}

Secondly, in the “buy tickets” section of the App interface, when the user chooses a seat, the App will send the following operation to select the seat:

{
  "intent": "operation.air-europe.select-seat",
  "entities": [
    {
      "type": "ent.seat-number",
      "entity": "A24",
      "canon": "a24"
    }
  ]
}

Docs:

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

handover-genesys dialogs

Description of the handover-genesys dialogs that use the bypass mode. Currently, these dialogs are only available for WhatsApp channel.

Introduction

The Github repository handover-genesys includes the available family of dialogs for the management of the handover use case for WhatsApp channel.

The dialog handover-bypass-dialog.ts uses the bypass mode to allow a direct connection with Genesys and, once activated, aura-bot directly sends the communication to a Genesys’ agent.

Remember that the main functionality of bypass mode, is that once we are in bypass mode within a conversation, any input message to the aura-bot will be directly sent to the external service. Likewise, any message from the external service will be shown to the user without going through aura-bot recognition system.

Settings

This section describes the configuration of handover-bypass-dialog.ts dialog in aura-configuration-api.

Currently, this dialog is exclusively configured for WhatsApp channel and certain intents. Check the configuration in the settings/ repository, by OB and language.

An extract of the dialog-config.json file is included below:

{
      "id": "handover-bypass",
      "suggestions": false,
      "triggerConditions": [
        {
          "intent": "intent.common.handover"
        },
        {
          "intent": "intent.common.help"
        },
        {
          "intent": "intent.miscellaneous.advice"
        }
      ],
      "onlyIn": [
        "whatsapp",
        "whatsapp2"
      ]
    },

I18n

key	example (es-cr)
`handover:handover.connect-to-agent`	Debido a la naturaleza de tu petición, vamos a intentar ponerte en contacto con un agente de nuestro servicio de atención.
`handover:handover.end-of-handover`	Recuerda que puedo seguir ayudándote.
`handover:handover.error-connecting-to-agent`	Se ha producido un error y no podemos contactar con los agentes, recuerda que seguimos atendiéndote en el 1004 y Movistar.es. También puedes intentarlo más tarde.
`handover:handover.error-message-to-genesys`	Se ha producido un error al enviar tu mensaje.
`handover:handover.off-hours-message`	Recuerda que seguimos atendiéndote en el 1004 y Movistar.es.
`handover:handover.unexpected-error`	Se ha producido un error y no podemos contactar con los agentes, recuerda que seguimos atendiéndote en el 1004 y Movistar.es. También puedes intentarlo más tarde.

Flows

If the recognized intent for a user’s message is handled by handover-genesys dialogs, the main dialog will pass the conversational flow to it.

Validating the incoming message

aura-bridge sends all messages from Handover with auraCommand information in channelData. The auraCommand has the following format:

{
   type: AuraCommandType.Suggestion,
   value: { intent: env.AURA_GENESYS_AURA_COMMAND_DEFAULT_INTENT }
}

Therefore, if the AURA_GENESYS_AURA_COMMAND_DEFAULT_INTENT environment variable value is set with the intent associated with this dialog, all messages from Handover will be managed by this one regardless of the bypass state (the aura-bot recognizers will send it directly to the associated dialog with the intent).

This also implies that a Handover message can arrive and there is not a chat session opened with Handover. To deal with this behavior, a new step has been added: validatorMessageStep.

In this previous step to validate the incomming message, if the message has been sent from Handover and the bypass model is not in conversationData (bypass not created), then the message is ignored. Otherwise, the message will be processed by the next step: startStep.

Start bypass mode

The first time a user accesses this dialog, the cached information about bypass mode will not exist in the conversationData, so the OnInit step of the dialog will be invoked to start the communication with the Handover system.

At the beginning of the process, the dialog will create the bypass model with the following initial values:

Bypass state: Init
Genesys connection state: Connecting
Bypass model TTL: Value of the HANDOVER_BYPASS_MODEL_TTL variable

Afterwards, the dialog will send a information message to the user (handover:handover.connect-to-agent) and you will make a request to the Genesys Request Chat endpoint using genesis-api-client.

The request to connect with Genesys contains the following information:

{
      "nickname": "", // Obtained from the information sent by the bridge or at its defect activity.from.id
      "userData": {}  // Detailed in "User Data profiles" section
}

If the connection was made correctly, we will have a new chat to communicate with Handover identified by the field chatId. Immediately, and using the information obtained in the previous step, the previous message exchanged between the user and Aura will be sent to Genesys using Genesys Send Message endpoint.

Format is described in Message history format

Finally, the dialog will keep the bypass model in conversationData as follows:

Bypass state: Bypass
Genesys connection state: Connected
Session: Chat information obtained in response to the call Genesys Request Chat

If the variable HANDOVER_ALWAYS_USE_REMOTE_CACHE is configured to true, data will be saved remotely in the cache.

@startuml
title Start bypass mode

actor User
participant Channel #2f9c3c
participant Bridge #3275a8
participant Bot #ebba65
participant NLPRecognizerMiddleware
participant BypassModeMiddleware
participant BypassDialog
participant Genesys #ebdff7

User->Channel: Write: "I want to speak with agent"
Channel->Bridge: Channel Message Request
Note right of Channel: <example>
Bridge->Bot: DL Message
Note right of Bridge: <example>
Bot->NLPRecognizerMiddleware: recognize from context
NLPRecognizerMiddleware->NLPRecognizerMiddleware: recognized intent: intent.common.handover
NLPRecognizerMiddleware->BypassModeMiddleware: request context
Note right of BypassModeMiddleware: does nothing
BypassModeMiddleware->BypassDialog: request context
BypassDialog->BypassDialog: OnInit
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "handover:WA.handover.connect-to-agent"
Note right of BypassDialog: Set bypass to "Init" state
BypassDialog->Genesys: Request Chat
Genesys->BypassDialog:
BypassDialog->Genesys: Send Message (message history)
Genesys->BypassDialog:
Note right of BypassDialog: Set bypass to "Bypass" state
Genesys->Bridge: PushNotification - Conversation starter messages with genesys
Bridge->Bot:
Note right of Bot: For simplicity, we did not add the full bot sequence diagram
Bot->Bridge:
Bridge->Channel:
Channel->User: Conversation starter messages with genesys

@enduml

Error connecting with Handover

In case of error when the request is made to the Genesys Request Chat endpoint using genesis-api-client, the bypass model information will be deleted in conversationData, error logs informations will be generated and the message handover:handover.error-connecting-to-agent to the user will be sent.

@startuml
title Error connecting with handover

actor User
participant Channel #2f9c3c
participant Bridge #3275a8
participant Bot #ebba65
participant NLPRecognizerMiddleware
participant BypassModeMiddleware
participant BypassDialog
participant Genesys #ebdff7

User->Channel: Write: "I want to speak with agent"
Channel->Bridge: Channel Message Request
Note right of Channel: <example>
Bridge->Bot: DL Message
Note right of Bridge: <example>
Bot->NLPRecognizerMiddleware: recognize from context
NLPRecognizerMiddleware->NLPRecognizerMiddleware: recognized intent: intent.handover.bypass.init
NLPRecognizerMiddleware->BypassModeMiddleware: request context
Note right of BypassModeMiddleware: does nothing
BypassModeMiddleware->BypassDialog: request context
BypassDialog->BypassDialog: OnInit
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "handover:WA.handover.connect-to-agent"
BypassDialog->Genesys: Request Chat
Genesys->BypassDialog:
BypassDialog->BypassDialog: Capture and log error
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "handover:WA.handover.error-connecting-to-agent"

@enduml

Sending user messages

Being in a bypass state, any message received in the dialog will be processed by the onByPass method.

Once the bypass mode has started (see Start bypass mode), any user message will be sent to Genesys using sendGenesysMessageToAgent (genesis-api-client).

Then, the bypass model is updated with the alias field returned by the previous call.

If an error occurs, error logs will be generated and an error message will be sent to the user with handover:handover.error-message-to-genesys key.

Receiving agent or system messages

Being in a bypass state, any message received in the dialog will be processed by the onByPass method.

When a message is received from Genesys, the message handler returns a function to handle this message using participantType and eventType fields.

Messages currently handled (using eventType) for agent or system:

message. Debug logs will be generated and the message of context.activity.text is sent to the user using sendActivity.

@startuml
title Agent or System send information

actor User
participant Agent #ebdff7
participant Channel #2f9c3c
participant Bridge #3275a8
participant Bot #ebba65
participant BypassModeMiddleware
participant BypassDialog

Agent->Bridge: Write: "Hello, I am an Agent, how can I help you?"
Bridge->Bot: DL Message
Bot->BypassModeMiddleware: request context
Note right of BypassModeMiddleware: bypass state (continue)
BypassModeMiddleware->BypassDialog: request context
BypassDialog->BypassDialog: OnBypass
BypassDialog->BypassDialog: externalMessageHandler.message
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "Hello, I am an Agent, how can I help you?"

@enduml

Conversation close

The conversation can only be closed by Genesys. To close the conversation, Genesys will send a closing message with quit-reason-code information (GCTI_SYSTEM field).

When the dialog receives this information, the message handler returns a function to handle this message using participantType (Client) and eventType (ParticipantLeft) fields:

participantLeft. It closes the bypass (the bypass model information will be deleted in conversationData) and sends activity to the user with handover:handover.end-of-handover message.

The Handover offhours section describes the closing process in detail.

Handover offhours

When Genesys is in offhours state, the connection will normally be done as described by the process Start bypass mode, but it will immediately send information indicating that it is in offhours state.

Any information message sent by Genesys will be sent to the user using sendActivity. After this, Genesys will send a closing message with quit-reason-code equal to 5 (GCTI_SYSTEM field).

{
   "from": {
         "nickname": "UserNickname",
         "participantId": 1,
         "type": "Client"
   },
   "index": 4,
   "type": "ParticipantLeft",
   "utcTime": 1616662697000,
   "eventAttributes": {
         "GCTI_SYSTEM": {
            "quit-reason-code": "5"
         }
   }
}

In this case, the message handler returns a function to handle this message using participantType (Client) and eventType (ParticipantLeft) fields.

participantLeft. It closes the bypass (the bypass model information will be deleted in conversationData) and sends activity to user with handover:handover.off-hours-message message.

@startuml
title Handover off hours

actor User
participant Channel #2f9c3c
participant Bridge #3275a8
participant Bot #ebba65
participant NLPRecognizerMiddleware
participant BypassModeMiddleware
participant BypassDialog
participant Genesys #ebdff7

User->Channel: Write: "I want to speak with agent"
Channel->Bridge: Channel Message Request
Bridge->Bot: DL Message
Bot->NLPRecognizerMiddleware: recognize from context
NLPRecognizerMiddleware->NLPRecognizerMiddleware: recognized intent: intent.handover.bypass.init
NLPRecognizerMiddleware->BypassModeMiddleware: request context
Note right of BypassModeMiddleware: does nothing
BypassModeMiddleware->BypassDialog: request context
BypassDialog->BypassDialog: OnInit
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "handover:WA.handover.connect-to-agent"
BypassDialog->Genesys: Request Chat
Genesys->BypassDialog:
Note right of BypassDialog: Create conversationData.bypassMode with default data and status BYPASS
Genesys->Bridge: Hello! Yes, this is an automated message because we are not available right now ...
Bridge->Bot: DL Message
Bot->BypassModeMiddleware: request context
Note right of BypassModeMiddleware: bypass state (continue)
BypassModeMiddleware->BypassDialog: request context
BypassDialog->BypassDialog: OnBypass
BypassDialog->BypassDialog: externalMessageHandler.message
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "Hello! Yes, this is an automated ..."

Genesys->Bridge: ParticipantLeft (quit-reason-code: "5")
Bridge->Bot: DL Message
Bot->BypassModeMiddleware: request context
Note right of BypassModeMiddleware: bypass state (continue)
BypassModeMiddleware->BypassDialog: request context
BypassDialog->BypassDialog: OnBypass
BypassDialog->BypassDialog: clientMessageHandler.participantLeft
Note right of BypassDialog: close bypass
BypassDialog->Bot:
Bot->Bridge:
Bridge->Channel:
Channel->User: Message: "handover:handover.off-hours-message"

@enduml

Non-controlled exceptions

If an error not indicated previously in the flows occurs in any procedure, error logs information will be generated and the message handover:handover.unexpected-error to the user will be sent.

Settings

This section lists and describes all the variables the handover-genesys dialog uses and that can be configured to adapt the environment:

Property	Type	Description
HANDOVER_BYPASS_MODEL_TTL	number	Bypass model TTL. By default: `25`
HANDOVER_CHAT_SERVICE_NAME	string	Genesys chat service name. By default: `request-whatsapp-aura`
HANDOVER_CHECK_STATUS_CHAT_SERVICE_NAME	string	Genesys chat service name to testing. By default: `request-whatsapp-testaura`
HANDOVER_USERDATA_GCTI_GMS_NODEGROUP	string	userData value to `GCTI_GMS_NODEGROUP`. By default: `GMS_Cluster`
HANDOVER_CLIENT_BASIC_AUTH_NAME	string	User for basic authentication in genesys api. By default ``
HANDOVER_CLIENT_BASIC_AUTH_PASSWORD	string	Password for basic authentication in genesys-api. By default ``
HANDOVER_CLIENT_BASE_PATH_URL	string	Base path to genesis-api-client.
HANDOVER_ALWAYS_USE_REMOTE_CACHE	boolean	Always use remote cache to keep conversation. By default: `false`

Message history format

As mentioned above, after connecting with Genesys, the message history is sent as an ordinary message. This message must meet the following format:

  (<DATE_ISO_FORMAT>)[<Usuario|AURA>]:<MESSAGE>

Example of message historic in the correct format:

   (2021-03-15T09:48:23)[Usuario]:Hola
   (2021-03-15T09:48:24)[AURA]:Hola. ¿Qué puedo hacer por ti?
   (2021-03-15T09:48:26)[Usuario]:¿Cuál es el importe de mi factura?

Connection’s profiles

The dialog can use a different profile to send specific data in userData on the request to Genesys Request Chat for each OB.

Currently, only the configuration for es is available.

es

userData field	value
userData[GCTI_GMS_PushDeviceId]	`AuraConversationData` model in base64
userData[GCTI_GMS_NodeGroup]	Value of HANDOVER_USERDATA_GCTI_GMS_NODEGROUP variable
userData[GCTI_Chat_AsyncMode]	true
userData[GCTI_Chat_PushSubscribe]	true
userData[GCTI_GMS_PushDeviceType]	customhttp
userData[GCTI_GMS_NotifyRequestor]	true
userData[GCTI_GMS_PushIncludePayload]	true
userData[GCTI_GMS_PushDebug]	true
userData[nickname]	Obtained from the information sent by the bridge or, failing that, from `activity.from.id`
userData[telefono]	activity.from.id
userData[TipoAtencion]	‘GP_Atencion’
userData[Origen_N1]	‘Whatsapp’
userData[RoutingEspecifico]	''

the field userData[GCTI_GMS_PushDeviceId] is an object that must implement the auraConversationData interface (defined in @telefonica/aura-utilities/lib/aura-models), but it is coded in base64 to be sent in the request as a string.

/**
 * @interface AuraConversationData
 * @description Information needed to keep the conversation between handover and the bot.
 */
export interface AuraConversationData {
    auraId: string;
    auraChannelId: string;
    conversationId: string;
    correlator: string;
    answerCallback?: string;
}

This field, therefore, must be decoded in base64 to be managed correctly.

Docs:

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

Guidelines for creating/migrating a dialog to channelData v3

Orderly steps for building or migrating a dialog to be compatible with channelData normalized model (version 3)

Introduction

If you want your use case to be compatible with the new channelData normalized model (v3), both for a new developed use case or for migrating an existing one, you should:

Develop the use case as explained in Building an Aura Bot dialog.
After that, carry out certain extra tasks that are orderly included in the following sections.

Examples in this section will be referenced to greetings dialog, which has been already prepared for channelData v3 version.

Create v3 folder

According to the general guidelines, all dialogs must be created inside the library’s src/ folder.

However, channelData v3 dialogs must be included in a v3 folder, within src/:

${your_library_root_folder}/src/v3

In this folder, you must place the dialog’s .ts files with the dialog’s implementation and the .spec.ts files for testing.

These files should specify the channelData version in the filename, for example: /my-dialog/newdialog-v3-dialog.ts.

Dialog’s id

The dialog’s id should include channelData version for its differentiation.

For example, in greetings dialog this is done appending v3 to the dialog’s id.

     * The id of the dialog.
     */
    public static id: string = 'greetings-v3';

Dialog configuration

Regarding the dialog’s configuration, which is found in the dialog-config.json file, inside settings/ folder, the channelData v3 dialog configuration must include a new property called channelDataVersion.

This property should be filled with the dialog’s version, in our use case v3. If no version is specified, it is understood that the dialog works in v1 mode (for classic use cases).

{
            "id": "greetings-v3",
            "channelDataVersion": "v3",
            "triggerConditions": [
                {
                    "intent": "intent.common.greetings"
                }
            ]
        }

It is also recommended to set suggestions to false in the dialog’s configuration.

{
            "id": "greetings-v3",
            "channelDataVersion": "v3",
            "suggestions": false,
            "triggerConditions": [
                {
                    "intent": "intent.common.greetings"
                }
            ]
        }

As shown in the example, the format for intents in channelData version 3 only changes internally. Therefore, when defining an intent, it is not necessary to specify its version, as the dialog loading system will do it internally.

Dialog implementation

Building a dialog in channelData v3 is quite similar to legacy channelData dialogs, whose process is fully explained in Building an Aura Bot dialog.The main difference is in the dialog’s output, which should be compatible with the channelData version’s schema.

For this case, the utility ChannelDataResponseMapper.formatChannelDataV3() creates a valid channelData v3 response and can be used with properties obtained from the Bot Framework’s context:

const correlator: string = ContextUtils.getCorrelator(stepContext.context);
const auraUser = ContextUtils.getAuraUser(stepContext.context);
const intentResult = DialogUtils.getDataActiveDialog(stepContext, 'options').intentResult;
const activity: Partial<Activity> = {
            text: this.localizer.getText('common:common.greetings.main', auraUser, correlator),
            channelData: ChannelDataResponseMapper.formatChannelDataV3(intentResult, intentConfigSettings, correlator)
        };

There is another important utility in this code snippet, ContextUtils.getIntentConfig(). It is used if there are configurations that refer to the same intent but have different implementations regarding channelData versions. This utility will obtain the dialog’s configuration based on this version.

Find the full waterfall step in the greetings dialog .

Dialog implementation extending existing dialogs

To avoid code repetition, you can reuse the code of existing v1 dialogs and extend it to be reused in v3 dialogs. To do this, follow these simple steps:

Modify your original v1 dialog to receive the dialogId as a param:

export default class ExampleDialog extends ComponentDialog {
    public static id: string = 'example-dialog';
    private configuration: Configuration;
    private logger: AuraLog;

    // Dialog id is received as a param or set to the original v1 value as default
    constructor(configuration: Configuration, id: string = ExampleDialog.id) {
        super(id);
        this.initialDialogId = id;

        this.logger = new AuraLog(id);
        this.configuration = configuration;

        super.addDialog(new WaterfallDialog(id, [
            this.examplePrompt.bind(this),
            this.exampleResult.bind(this),
        ]));
        const confirmCurrentPrompt = new ChoicePrompt(this.promptsNames.CONFIRM_CURRENT, PromptUtils.getRetriesValidator(0));
        confirmCurrentPrompt.style = ListStyle.heroCard;
        super.addDialog(confirmCurrentPrompt);
    }
    .
    .
    .

Create your v3 dialog extending your v1 dialog:

import {
    Configuration} from '@telefonica/aura-bot-utilities/lib/aura-bot-common';
import ExampleDialog from '../../whatsapp/otp-confirm-user-phone-number-dialog';
import OtpPhoneNumberV3Dialog from './otp-phone-number-v3-dialog';

/**
 * Aura bot dialog implementation for otp phone number TODO
 */
export default class ExampleV3Dialog extends ExampleDialog {
    /**
     * The id of the dialog.
     */
    public static id: string = 'otp-confirm-user-phone-number-v3-dialog';

    /**
     * Constructor dialog
     *
     * @param  {Configuration} configuration configuration dialog
     */
    constructor(configuration: Configuration) {
        super(configuration, ExampleV3Dialog.id);
    }
}

If your dialog does not modify the response channelData, the process is finished.
But if your original v1 dialog modifies some channelData values, you need to use auxiliary methods to create this channelData and overwrite them in the v3 dialog:

export default class ExampleDialog extends ComponentDialog {
    .
    .
    .
    private async registerUser(stepContext: WaterfallStepContext): Promise<DialogTurnResult> {
            const activity: Partial<Activity> = {
                type: 'message',
                text: getText('login.otp.success')
            };
            activity.channelData = await this.getRedirectChannelData(auraUser, this.configuration, this.logger, corr, dialogData?.originalIntent);

            await stepContext.context.sendActivity(activity);
    }

    protected async getRedirectChannelData(auraUser: AuraUserBaseModel<any>, configuration: Configuration, logger: AuraLog, corr: string, originalIntent?: Intent):
    Promise<AuraModels.ResponseChannelDataV3.ResponseChannelData | any> {
        return {
            customData: await LinkingUtils.checkTacAndRedirect(auraUser, this.configuration, this.logger, corr, originalIntent)
        };
    }
    .
    .
    .

export default class ExampleV3Dialog extends ExampleDialog {
    .
    .
    .
    protected async getRedirectChannelData(auraUser: AuraUserBaseModel<any>, configuration: Configuration, logger: AuraLog,
        corr: string, originalIntent?: Intent): Promise<AuraModels.ResponseChannelDataV3.ResponseChannelData> {
        const actions: AuraModels.ResponseChannelDataV3.Action[] = [];
        const redirectAction = await LinkingUtils.checkTacAndRedirectV3(auraUser, configuration, logger, corr, originalIntent);
        if (redirectAction) {
            actions.push(redirectAction);
        }
        return {
            actions
        };
    }
}

Docs:

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

mocks-v3 dialog

Description of the mocks-v3 dialog, responsible for handling mocked responses in use cases

Introduction to the mocks-v3 dialog

The mocks-v3 dialog is a new dialog that returns mocked responses of use cases to be used by developers.

These responses are returned in channelData V3 format.

Find here the source code of the dialog’s file mocks-dialog.ts.

How it works

The mocks-v3 dialog gets a mocked response from a blob in Azure Storage, it formats the response in a message with a channelData in version v3 and send it to the user. This mocked responses are part of the library resources and are uploaded to Azure Blob Storage during the make-up process, but new ones could be uploaded directly to Azure Blob Storage and will be returned by the dialog.

The mocks-v3 dialog updates the mock files cache if it is older than 2 minutes (or the configured value in MOCKSV3_ACCESS_AZURE_CONTAINER_TIMEOUT_MS environment variable).

These mocked files are stored in the static-resources container of Aura’s Azure Storage instance of the deployment, within the path:
libraries/mocks/${channelPrefix}/${intent}

The files will have the entities values, alphabetically sorted and joined with - as filename.

For example, if the mocked response has these values:

{
  "intent": "intent.tv.search",
  "entities": [
    {
"entity": "temporada 3",
"type": "ent.audiovisual_tv_season_number",
"score": 0.0,
"start_index": 29,
"end_index": 41,
"canon": "3 temporada",
"label": null
    },
    {
"entity": "episodio 1",
"type": "ent.audiovisual_tv_episode_number",
"score": 0.0,
"start_index": 16,
"end_index": 28,
"canon": "1 capítulo",
"label": null
    }
  ]
}

Then, the name of the file will be episodio_1-temporada_3.json and if the channel is set-top-box the complete route will be:
static-resources/libraries/mocks/stb/intent.tv.search/episodio_1-temporada_3.json

With these names, the mock will match the recognized intents and entities to find the correct mocked response to be returned.

Currently configured responses

The next table shows current responses configured in the mocks-v3 dialog:

Intent	Entity	Aura Command	Phrase	Response
`intent.tv.search`	La Resistencia	`"auraCommand": { "type": "suggestion", "value": { "intent": "intent.tv.search","entities": [{ "entity": "La Resistencia", "type": "ent.audiovisual_tvshow_title", "canon": "La Resistencia", "score": 1 }]}}`	Busca La Resistencia	Tv search with 0 results
`intent.tv.search`	fútbol	`"auraCommand": { "type": "suggestion", "value": { "intent": "intent.tv.search", "entities": [{ "entity": "fútbol","type": "ent.audiovisual_sports", "canon": "fútbol", "score": 1 }]}}`	Busca fútbol	Tv search with 1 result (`catalog_type`=`LIVE` and `content_type`=`live_episode`)
`intent.tv.search`	Virtual Hero	`"auraCommand": { "type": "suggestion", "value": { "intent": "intent.tv.search", "entities": [ { "entity": "Virtual Hero", "type": "ent.audiovisual_tvseries_title", "canon": "Virtual Hero", "score": 1 }]}}`	Busca Virtual Hero	Tv search with multiple results
`intent.tv.search`	Star Wars	`"auraCommand": { "type": "suggestion", "value": { "intent": "intent.tv.search", "entities": [{ "entity": "Star Wars", "type": "ent.audiovisual_film_title", "canon": "Star Wars","score": 1 }]}}`	Búscame Star Wars	tv.search with multiple third party results
`intent.tv.search`	Closer	`"auraCommand": { "type": "suggestion", "value": { "intent": "intent.tv.search", "entities": [{ "entity": "Closer", "type": "ent.audiovisual_film_title", "canon": "Closer", "score": 1 }]}}`	Búscame Closer	tv.search with third party result
`intent.tv.display`	Star Wars	`"auraCommand": { "type": "suggestion", "value": { "intent": "auraCommand", "entities": [{ "entity": "star wars", "type": "ent.audiovisual_film_title", "canon": "Star Wars", "score": 1 }]}}`	Pon Star Wars	tv.display with CONTENT.PLAY action and third party result
`intent.tv.display`	La princesa prometida	`"auraCommand": { "type": "suggestion", "value": { "intent": "intent.tv.display", "entities": [{ "entity": "La princesa prometida", "type": "ent.audiovisual_film_title", "canon": "La princesa prometida"," score": 1 }]}}`	Pon La princesa prometida	tv.display with CONTENT.PLAY action
`intent.tv.display`	Telecinco	`"auraCommand": {"type": "suggestion", "value": {"intent": "intent.tv.display","entities": [ {"entity": "telecinco","type": "ent.audiovisual_channel","canon": "Telecinco","score": 1}] }}`	Pon Telecinco	tv.display with CHANNEL.PLAY action

Environment variables

Name	Default value	Description
MOCKSV3_ACCESS_AZURE_CONTAINER_TIMEOUT_MS	120000	Time to refresh Azure blob storage files cache
AURA_RESOURCES_PREFIX	libraries	Base folder in `static-resources` where dialog files are stored

Dates and country codes

⚠️ Dates
Date fields like start, end, release_date and expiration_date should be formatted to ISO-8601 UTC according to Kernel documentation.
Currently, in Kernel response, start and end do not match the format and these fields are modified in mock responses manually.
⚠️ Country codes
Country fields like original_language_code, audios and subtiltes should follow the ISO 639-2 format, but currently, none of these fields follow this standard in Kernel responses. Therefore, these fields are modified in mock responses to follow the standard.
default_language_order is not present in current mock responses but should be a combination between two ISO 639-1 country codes.

Docs:

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

suggestions dialog v3

Description of the suggestions dialog v3 that allows sending suggestions to the user

Introduction

ℹ️ This is an aura-bot core dialog, deployed jointly with the corresponding Aura Platform release.

The aim of the suggestions dialog v3 is precisely to send suggestions to the user related to the current conversation. This can help the user get the information he needs quickly using these suggestions.

This dialog is closely related to the main dialog. The main dialog will execute the suggestions dialog if the suggestions property is true in aura-configuration-api server or suggestions property is true in settings of triggerConditions of generic-dialog-v3 dialog.

Find here the source code of the dialog’s file suggestions-v3.ts.

Settings

The suggestions dialog v3 is part of the aura-bot core, so it does not have a specific section in the ChannelConfiguration model.

As previously indicated, each dialog can activate suggestions using the suggestions field in its own section.

An extract of the dialog-config.json file is included below:

Example for generic-dialog-v3 dialog:

        {
            "id": "generic-dialog-v3",
            "channelDataVersion": "v3",
            "triggerConditions": [
            {
                    "intent": "intent.tv.init",
                    "settings": {
                        "locales": {
                            "success": [
                                "tv:tv.init.start"
                            ],
                            "error": [
                                "tv:tv.error.fpaOrCognitive"
                            ]
                        },
                        "sound": "positive",
                        "needPlayingContent": false,
                        "payloadType": "tv",
                        "suggestions": true
                    }
                }
            ]
        }

This snippet shows how to execute the suggestions dialog v3 after the generic-v3-dialog dialog is executed.

Example for none-v3 dialog:

    {
      "triggerConditions": [
        {
          "intent": "None"
        }
      ],
      "id": "none-v3",
      "channelDataVersion": "v3",
      "suggestions": true
    }

This snippet shows how to execute the suggestions dialog v3 after the none-v3-dialog dialog is executed.

How it works

If the suggestions property is true for the running dialog, the main dialog will pass the conversational flow to suggestions dialog v3 in the suggestions step.

Currently, the dialog get suggestions data of aura-configuration-api, Obtaining suggestions randomly, the number of suggestions configured globally or per channel.

Configuration variables used globally

This section lists all the variables that the suggestions dialog v3 uses and can be configured to adapt the environment:

Property	Type	Description
AURA_SUGGESTIONS_V3_NUMBER	string	Number of suggestions configured to be returned in channel data version 3. By default, `5`.

Configuration variables used per channel

responseOptions.suggestionsNumber has been added to the channel response optionally, so if it is not configured, the global configuration prevails.

Configuration template suggestions

the suggestions dialog v3 return suggestion data as an attachment with a new template defined with contentType: application/vnd.telefonica.aura.suggestion

Example response:

{
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.telefonica.aura.suggestion",
            "content": {
                "suggestions": [
                    {
                        "title": "suggestions:tv.search.byGenderViaChannel.suggestion.button",
                        "value": {
                            "intent": "intent.tv.content_get_info",
                            "entities": [
                                {
                                    "canon": "Discovery",
                                    "entity": "Discovery",
                                    "label": "",
                                    "score": 1,
                                    "type": "ent.audiovisual_channel"
                                },
                                {
                                    "canon": "documentales",
                                    "entity": "Documentales",
                                    "label": "DC",
                                    "score": 1,
                                    "type": "ent.audiovisual_genre"
                                }
                            ]
                        }
                    },
                    {
                        "title": "suggestions:tv.searchSportByTeam.suggestion.button",
                        "value": {
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "canon": "estudiantes",
                                    "entity": "Estudiantes",
                                    "label": "",
                                    "score": 1,
                                    "type": "ent.audiovisual_sports_team"
                                }
                            ]
                        }
                    },
                    {
                        "title": "suggestions:tv.search.byGenderViaChannel.suggestion.button",
                        "value": {
                            "intent": "intent.tv.content_get_info",
                            "entities": [
                                {
                                    "canon": "Telecinco",
                                    "entity": "Telecinco",
                                    "label": "",
                                    "score": 1,
                                    "type": "ent.audiovisual_channel"
                                },
                                {
                                    "canon": "programas de televisión",
                                    "entity": "Programas",
                                    "label": "PR",
                                    "score": 1,
                                    "type": "ent.audiovisual_genre"
                                }
                            ]
                        }
                    },
                    {
                        "title": "suggestions:tv.search.byGender.suggestion.button",
                        "value": {
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "canon": "películas",
                                    "entity": "película",
                                    "label": "CN",
                                    "score": 1,
                                    "type": "ent.audiovisual_genre"
                                }
                            ]
                        }
                    },
                    {
                        "title": "suggestions:tv.search.byActor.suggestion.button",
                        "value": {
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "canon": "Mario Casas",
                                    "entity": "Mario Casas",
                                    "label": "",
                                    "score": 1,
                                    "type": "ent.audiovisual_actor"
                                },
                                {
                                    "canon": "películas",
                                    "entity": "películas",
                                    "label": "CN",
                                    "score": 1,
                                    "type": "ent.audiovisual_genre"
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

I18n

key	description
`suggestions:${titleResource.name}`	Used to get cardAction title name from suggestion when the suggestion resource is `button` type

Docs:

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

Use cases for testing Aura

Libraries for testing different Aura Platform functionalities

Introduction

The Github library aura-bot-libraries-test contains different libraries and dialogs used by the Aura Global Team for testing Aura.

Check the Github repository:
https://github.com/Telefonica/aura-bot-libraries-test/tree/master/packages

It includes several examples generated by APE for testing the use of certain Aura features and the factotum library that integrates test dialogs related to Aura core functionalities.

Within the factotum library, several dialogs are included for the management of the handover use case for the WhatsApp channel:

handover-genesys dialogs

The different dialogs from the GitHub repository will be progressively documented here in upcoming releases

Docs:

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

Description of the whatsapp-otp-login dialog, that handles SMS-OTP authentication in this channel

Introduction

The whatsapp-otp-login dialog is a global dialog to make the user login in the WhatApp channel.

Currently, it only supports SMS-OTP authentication.

Access to the Kernel WhatsApp API.

📃 Check the dialog’s code in the aura-bot-libraries Github repository.

Flows

The dialog flow is divided in several steps, which are described in the following sections.

Additionally, a sequence flow is included in Operational flowcharts: WhatsApp OTP (LoA2) authentication.

Check if the user is already authenticated

When the dialog flow starts, it checks if the current user is already authenticated, verifying if the type of user is anonymous.

If so, the dialog flow ends with the text resource login.otp.already.signin. If not, it starts a sub-dialog to verify the phone number to send the SMS code.

Check if current number is corporate

In this step, if configured so, the system checks if the current phone number is corporate, to allow using it in next steps.

If check is not enabled or user is not corporate, go to the following step for prompting a new phone number.
Otherwise, ask the user if she wants to use current number.

Prompt a phone number

This step prompts the user to enter the phone number he wants to log in with in Aura, thus the dialog will send the SMS-OTP code to that phone number.

If the phone number format is correct:
1. If configured to check the prompted number and the number is not corporate, ask for a new phone number (until max number of retries is reached).
2. Otherwise, it starts a sub-dialog to verify the SMS authcode.
If the format is wrong, the dialog will prompt again to enter with correct format until the maximum number of attempts is reached (See settings section). When the user reaches this maximum, the dialog ends with the text resource login.otp.too.many.phone.kos.

To send this code to the user phone, the send code endpoint from Kernel is called. This endpoint returns an authentication_id that will be used in the next step to validate the OTP code.

Insert SMS OTP code

This step prompts the user to enter the SMS authcode sent to phone number provided on the previous step.

When the user enters the correct code, the dialog starts the following step in order to register the user.
If the authcode is wrong, the dialog will prompt again to enter the correct authcode until the maximum number of attempts is reached (See settings section).

When the user reaches the maximum authcode attempts the dialog ends with the text resource login.otp.too.many.sms.kos. A new code can be sent by sending the text resource login.otp.newCode.command which makes the bot to send a new auth code to the phone number provided.

To validate the code, the Kernel validate code endpoint is called with the code received by the user and the authentication_id returned in the previous api call. This call returns all the necessary data to register the user in Aura.

Register user

This step registers the user in Aura ecosystem and redirects to onboarding T&C with the intent intent.onboarding.terms-and-conditions or the requested intent before authentication if T&C are already accepted.

To do this registry, the method GET /users/aura-id/{auraId} from aura-authentication-api is called and the user is registered with the data obtained from Kernel in the previous step.

The redirect to onboarding (or the intent set) is done if the field actions.afterLogin is present in the channel configuration. An example of this configuration is shown below:

 {
  "name": "whatsapp",
  "prefix": "wa",
  "type": "whatsapp",
  "responseOptions": {
      "versions": {
          "v1": {
            "singleMessage": true,
          }
      }
  }
  .
  .
  .
  "actions": 
    "afterLogin": {
        "type": "redirect",
        "action": "REDIRECT.COMMAND",
        "data": {
            "auraCommand": {
            "type": "suggestion",
            "value": {
                "intent": "intent.onboarding.terms-and-conditions"
            }
            }
        }
    }
  }
  .
  .
  .

This configuration is used to generate the redirect command that will be sent to launch the intent. If there is an intent requested before authentication and the T&C are already accepted, the intent set in configuration will be overwritten with the requested intent.

NOTE The user can cancel login flow at any moment by sending the text resource login.otp.cancel.command.

Sequence diagram

sequenceDiagram
    autonumber
    participant user
    participant auraBridge
    participant auraBot
    participant 4p
    participant auraAuth
    participant T&C API
    rect rgb(255, 255, 230)
    Note left of user: USER REQUESTS AN AUTHENTICATED UC
    user->>auraBridge: I want to see my billing data
    auraBridge->>auraBot: 
    auraBot->>auraBot: Dialog needs auth and user is anonymous. Redirect to whatsapp login
    auraBot->>auraBridge:  
    auraBridge->>user: login.otp.phone.number: Please enter your phone number
    user->>auraBridge: +34665762892
    auraBridge->>auraBot: 
    auraBot->>4p: Aura requests a new OTP sms
    4p->>user: (SMS) login.otp.sms.code.message: Your verification code is 6789
    4p->>auraBot: authorization_id
    auraBot->>auraBridge: 
    auraBridge->>user: login.otp.sms.sent.message: Please insert the code
    user->>auraBridge: 6789
    auraBridge->>auraBot: 
    auraBot->>4p: Aura validates the code
    4p->>auraBot: Returns user data
    auraBot->>auraAuth: Register user
    auraAuth->>auraBot: 200 OK
    alt
        Note left of T&C API: User already accepted authenticated T&C
        auraBot->>T&C API: Checks terms and conditions
        T&C API->>auraBot: 200 OK
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.billing from redirect intent
        auraBot->>auraBot: authenticates the user and executes the billing dialog
        auraBot->>auraBridge: 
        auraBridge->>user: "Here is your billing data"
    else
        Note left of T&C API: User needs to accept authenticated T&C
        auraBot->>T&C API: Checks terms and conditions
        T&C API->>auraBot: 404 Not found
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.onboarding.terms-and-conditions from redirect intent
        auraBot->>auraBot: authenticates the user and executes T&C dialog
        auraBot->>auraBridge: 
        auraBridge->>user: onboarding:onboarding.auth.welcome
        auraBridge->>user: onboarding:onboarding.auth.privacy
        auraBridge->>user: onboarding:onboarding.auth.terms-and-conditions
    else
        Note left of T&C API: Channel doesn't have terms and conditions config
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.billing from redirect intent
        auraBot->>auraBot: authenticates the user and executes the billing dialog
        auraBot->>auraBridge: 
        auraBridge->>user: "Here is your billing data"
    end
end

BotResponse settings

Currently, the dialog has a main intent intent.authentication.login and three auxiliary intents: otp-confirm-user-phone-number-dialog, intent.authentication.otp.phone.number and intent.authentication.otp.auth.code. These auxiliary intents are necessary to enable the flow between sub-dialogs.

        {
            "id": "whatsapp-otp-login-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.login"
                }
            ]
        },
        {
            "id": "otp-confirm-user-phone-number-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.otp.confirm.user.phone.number.dialog"
                }
            ]
        },
        {
            "id": "otp-phone-number-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.otp.phone.number"
                }
            ]
        },
        {
            "id": "otp-sms-auth-code-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.otp.auth.code"
                }
            ]
        }

Settings

This section lists and describes all the variables the whatsapp-otp-login dialog uses and that can be configured to adapt the environment:

Property	Type	Description	Default value
LINKING_FP_WHATSAPP_ENDPOINT	string	WhatsApp API endpoint
LINKING_WA_MAX_FP_SEND_SMS_RETRIES	number	Maximum SMS retries.	3
LINKING_WA_MAX_AUTHCODE_RETRIES	number	Maximum authcode retries.	3
LINKING_WA_MAX_PHONENUMBER_RETRIES	number	Maximum phonenumber retries.	3

Docs:

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

unexpected-file dialog

Description of the unexpected-file dialog for the management of unforeseen files

Introduction

ℹ️ This is an aura-bot core dialog, deployed jointly with the corresponding Aura Platform release.

The aim of the unexpected-file dialog is to be triggered when a attachment is received on aura-bot, but it is not being expected.

The prerequisite for a file being expected is either a active bypass dialog that accept attachments or a dialog with an active AttachmentPrompt.

Find here the source code of the dialog’s file unexpected-file.ts.

I18n

key	description
`core:unexpected.file`	Error message of file attachments not supported

Flow

The unexpected-file dialog is closely related to file-manager recognizer.

When the recognizer detects a valid attachments data and the channel supports attachments, then it will check if a dialog capable of handling attachments is executing. Otherwise, it will pass the attachment to the unexpected-file dialog

Docs:

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

whatsapp-logout dialog

Description of the whatsapp-logout dialog, that handles the log out process for this channel

Introduction

The whatsapp-logout dialog is a global dialog in charge of the user’s logout in the WhatsApp channel.

📃 Check the dialog’s code in the aura-bot-libraries Github repository.

Flows

The flow of this dialog is simple. In the first step, a prompt is returned to the user to confirm if he wants to logout.

After that, if he accepts, certain actions are performed:

The user is deleted in Aura database calling the aura services API. If this call fails, an error will be returned, and the logout will fail.
The user is deleted in Kernel calling the logout endpoint. If this call fails, the flow continues normally returning a success message to the user and only showing an error log.
If the user is logged with LoA3, access session is deleted in Kernel calling access session delete endpoint. If this call fails, the flow continues normally returning a success message and only showing the error in logs.
The local cache is set to invalid to force the refresh next time the user interacts with Aura.

Docs:

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

Migrate use cases to Bot Framework 4.19

Guidelines for the migration of use cases to Bot Framework 4.19, which is the version used by Aura’s upcoming architecture based on Microsoft skills protocol

Introduction

Due to Bot Framework Skills implementation in Aura, aura-bot components have been updated to use Microsoft Bot Framework version 4.19.0.

Therefore, local use cases must be migrated in order to be compatible with this version.

The guidelines for the migration of use cases are summarized in the current document.

:warning:

The upgrade to Microsoft Bot Framework 4.19.0. comes together with the upgrade of node and other aura-bot dependencies in order to make Aura work properly.

For this purpose, OBs must follow the guidelines Node and dependencies upgrade.

Changes for use cases migration

In this section, a list of mandatory and recommended changes are explained, but consider applying them both, as it will prevent future incompatibilities.

Mandatory changes

Bot Framework version

The following dependencies must be included in the package.json file and set to 4.19.0 version:

{
    "botbuilder": "~4.19.0",
    "botbuilder-dialogs": "~4.19.0",
    "botbuilder-core": "~4.19.0",
}

Joi version

Joi must be updated to version 17 in the use case package.json file:

{
    "joi": "^17.6.0",
}

Keep in mind that any package followed by @hapi/joi and its types should be removed from package.json:

{
    "@types/hapi__joi": "^16.0.12",
    "@hapi/joi": "16.1.5",
}

Aura components version

All components from @telefonica private npm’s repository must be updated to release version 8.

Here is an example of how they should be defined in a package.json file:

{
    "@telefonica/aura-bot-common": "^8.0.0",
    "@telefonica/aura-movistar-libraries-utilities": "^8.0.0",
    "@telefonica/aura-bot-library-util": "^8.0.0",
}

Recommended changes

In this section, changes which have been applied in the base code of aura-bot components are included.

⚠️ We highly encourage applying them, in addition to the mandatory changes.

aura-clients

There has been a big overhaul in client generation, using superagent 8, and in its auto-generation. In the document create/update an API client, the guidelines to use and generate them are included.

Our recommendation is to generate clients using these tools and use the already generated ones into your new developments.

eslint

We are migrating from tslint to eslint, due to its deprecation.

For this purpose, we recommend using our unified set of rules, which are defined in @telefonica/eslint-config-aura which can be found in npmjs.

Here is an example of how to apply this configuration to a project:

Create a .eslintrc.js with the following configuration:

module.exports = {
    extends : [
        '@telefonica/aura'
    ]
};

Add these dependencies to package.json:

...
    "devDependencies": {
        "@telefonica/eslint-config-aura": "1.0.0",
        "@typescript-eslint/eslint-plugin": "^5.50.0",
        "@typescript-eslint/parser": "^5.50.0",
        "eslint": "^8.33.0",
        "eslint-plugin-import": "^2.27.5",
        "eslint-plugin-jsdoc": "^39.7.5",
    },
...

Jest

We are migrating from Mocha to Jest, which is our testing library.

We encourage developers to use it in new implementations.

Making HTTP/HTTPS requests

As a reminder, request and request-promise libraries have reached End Of Life and were deprecated 3 years ago.

The use of an alternative such as superagent 8 is highly recommended, as keeping using request and request-promise can expose vulnerabilities.

AuraLogging

The library @telefonica/aura-logging was modified internally, to increase performance and enhance usability. Minor modifications are required, in order to use the new interfaces, which simplify the instantiation process. Note that even though the new interface was added, and is the recommended way to use logging, the legacy system also works by now (it is deprecated, and legacy code will be removed in next versions).

We have to replace the old code, shown in the following snippet:

const logger = new AuraLogger.AuraBusEmitter('my-module');

With the new version:

const logger = new AuraLog('my-module');

On the other hand, it is recommended, but not necessary, adapting unit tests (in case the log calls are mocked), to mock the new interface.

Replace the code snippet shown below:

auraBusEmitterStub = stub(AuraLogger.AuraBusEmitter.prototype, 'emit');

With this one:

auraBusEmitterStub = stub(AuraLog.bus, 'emit');

Docs:

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

Migrate a use case to Evanescence 9.0.0 release

Evanescence 9.0.0 includes key modifications in aura-bot in order to keep Aura Platform up to date and improve its operation. For this reason, use cases dialogs created in previous releases must be migrated to be compatible with this version.

This document includes the guidelines for the migration of local use cases.

Introduction

Evanescence 9.0.0 release includes certain modifications and upgrades in botBuilder, nodejs version, Aura channels configuration, repos and libraries, etc. Due to these changes, use cases must be adapted in order to be aligned with the Aura Platform changes through the execution of mandatory and recommended modifications.

The modifications in aura-bot are summarized below, together with the required changes to execute in local use cases, which are fully detailed in succeeding sections:

Update of Node.js to version 20.0.0, to keep Aura platform up to date.
- Mandatory change of package.json file.
- Mandatory change of use case dialog code.
Update of Bot Framework version to version 4.22.1, to keep Aura platform up to date.
- Mandatory change of package.json file.
- Mandatory change of use case dialog code.
Update Aura channel data model (information about channels stored in the platform) to eliminate the extra effort of maintaining the platform internal components using different channel data models.
- Mandatory change of use case dialog code.
Reduction of the number of internal libraries to improve and streamline the platform release generation process:
- Mandatory change of use case dialog code.
Update to eslint2024, Typescript, dependencies
- Recommended modifications

Mandatory modifications

1. Change `package.json` file

Update the package.json file content as shown below:

{
    "name": "@my-registry/my-library",
    "version": "1.0.0",
    "main": "lib/index.js",
    "engines": {
        "node": ">=18.0.0"
    },
    "license": "UNLICENSED",
    "plugin": {
        "provides": [
            "my-service"
        ]
    },
    "dependencies": {
        "@telefonica/aura-bot-utilities": "^1.0.0",
        "@telefonica/aura-clients": "^1.0.0",
        "@telefonica/aura-utilities": "^1.0.0",
        "botbuilder": "~4.22.1",
        "botbuilder-dialogs": "~4.22.1",
        "joi": "^17.6.0",
        "moment": "^2.29.3"
    },
    "devDependencies": {
        "@types/jest": "^29.2.5",
        "@types/node": "^14.17.5",
        "@types/uuid": "^8.3.0",
        "jest": "^29.3.1",
        "jest-junit": "^15.0.0",
        "shx": "^0.3.3",
        "ts-jest": "^29.0.3",
        "ts-node": "^10.9.1",
        "typescript": "~5.0.0"
    },
    "scripts": {
        "build": "npm run clean && npm run compile",
        "clean": "cross-env shx rm -fR ./lib",
        "compile": "tsc"
    },
     "repository": {
        "type": "git",
        "url": "git@github.com:Telefonica/my-repository.git",
        "directory": "packages/my-library"
    }
}

2. Change use case dialog code

2.1 Due to Node.js update

No necessary changes have been identified and the current code should run correctly on Node.js version 20.0.0.
Some unit tests that make use of error messages generated by Node.js may need to be adapted.

2.2 Due to Bot Framework update

No necessary code changes have been identified and the current code should run correctly with BotFramework 4.22.1.
In any case, as shown in Section 1, Botbuilder dependencies must be updated in the package.json of all libraries:

"dependencies": {

   "botbuilder": "~4.22.1",
   "botbuilder-dialogs": "~4.22.1"

}

2.3 Due to the use of the current channel model

Update use cases dialogs to replace the references to the old data model with the new one:

All the imports of import {AuraChannel} from '@telefonica/aura-bot-common' should be changed to import { ChannelConfiguration } from '@telefonica/aura-clients/lib/aura-configuration-api-client'.
Also, all channel models imported from channel-models.ts in @telefonica/aura-bot-common should be imported from @telefonica/aura-clients/lib/aura-configuration-api-client.
user.channel will change its model from AuraChannel to ChannelConfiguration.
- With this change, certain accesses to properties should be changed:

Deprecated channel model field	Current channel model field
channel.scopes	channel.security?.authScopes
channel.purposes	channel.security?.authPurposes
channel.outputMessageFormat	channel.responseOptions?.outputMessageFormat
channel.fpaAuthIntegratedConfiguration.logoutCallback.channel_communication_query_params	channel.security.federatedAuthentication.logoutCallback.queryParams
channel.fpaAuthIntegratedConfiguration.logoutCallback.channel_communication_endpoint	channel.security.federatedAuthentication.logoutCallback.endpoint
channel.fpaAuthIntegratedConfiguration.logoutCallback	channel.security.federatedAuthentication.logoutCallback
channel.fpaAuthIntegratedConfiguration.channelUserSeparator	channel.security.federatedAuthentication.auraIdSeparator
channel.fpaAuthIntegratedConfiguration.channelCallback.channel_communication_query_params	channel.security.federatedAuthentication.loginCallback.queryParams
channel.fpaAuthIntegratedConfiguration.channelCallback.channel_communication_endpoint	channel.security.federatedAuthentication.loginCallback.endpoint
channel.fpaAuthIntegratedConfiguration.channelCallback	channel.security.federatedAuthentication.loginCallback
channel.fpaAuthIntegratedConfiguration.accountLinkingUrl	channel.security.federatedAuthentication.loginUrl
channel.fpaAuthIntegrated	channel.security?.federatedAuthentication
channel.dialogs	channel.dialogLibraries
channel.authentication?.anonymous	channel.security?.anonymous
channel.alwaysSpeak	channel.responseOptions?.sendSpeak
channel.allowUserProfile	channel.security?.allowUserProfile

2.4 Due to Aura libraries grouping

As Aura libraries have been grouped, it is required to update the imports in the use cases dialogs code:

Old imports	New imports
Imports from `@telefonica/aura-bot-common`	import * from `@telefonica/aura-bot-utilities/lib/aura-bot-common`
Imports from `@telefonica/aura-bot-library-util`	import * from `@telefonica/aura-bot-utilities/lib/aura-bot-library-util`
If using any of the Aura’s published API clients	import * from `@telefonica/aura-clients/lib/the-client-used` Check the current list of API clients in the document Aura API clients
If using any of the Aura’s published utilities	import * from `@telefonica/aura-utilities/lib/the-utility-used` Check the current list of utilities in the document: Aura utilities

Recommended modifications

In addition to the mandatory changes outlined in the previous sections, we highly recommend implementing the following additional adjustments:

Update to eslint 2024

eslint version is updated to 8.57.0. It is recommended to upgrade this component.

Update Typescript

Changes in tsconfig:
- Remove unnecessary libraries defined in lib field (DOM, etc.)
- The target field should be set to es2022 to make use of the latest capabilities of Nodejs 20.0.0
- The lib field should be set to es2023 (Typescript >= 5.2.2 is required)

{
    "compilerOptions": {
        "lib": [
            "ES2023"    // Typescript >= 5.2.2 is required
        ],
        "target": "2022",
        // ...
    }
    // ...
}

References:

Dependencies updates

Dependency	Version
superagent	superagent@8.1.2
UUID	uuid@9.0.1

Deprecations

Aura old channel model is deprecated. Access here the current channel model.
The use of request and request-promise is deprecated. The recommended dependency to use is superagent, but also got and axios are validated.
Further information: Making HTTP/HTTPS requests.
The use of zlib as a external library is deprecated.
The recommendation is to use the one included in node.js directly.

AuraLogger

Some releases ago, the version of AuraLogger was updated and, although the old version has been maintained until Dire Straits release, it will be removed in Evanescence release.

Please, follow the instructions for the new logger:

How to use aura-logging utility in Aura for controlling the login processes: aura-logging utility.
Migration from the old library @telefonica/aura-logging to the new one: AuraLogging.