1 - context-filter dialog
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:
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
}
}
]
2 - mocks-v3 dialog
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.
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.
3 - suggestions dialog V3
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 |
4 - unexpected-file dialog
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