Aura –

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

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

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