Aura Global use cases

• 1: Authentication dialogs
• 1.1: account-linking dialog
• 1.2: get-oauth-url dialog
• 1.3: account-remove dialog
• 1.4: seamless-account-remove dialog
• 1.5: onboarding-whatsapp dialog
• 1.6: whatsapp-otp-login dialog
• 1.7: whatsapp-logout dialog
• 2: Conversational dialog
• 3: generic-ai-dialog
• 3.1: Generic AI Dialog v1
• 3.2: Generic AI Dialog v3
• 4: generic-dialog
• 4.1: generic-dialog v1
• 4.2: generic-dialog-v3
• 5: Miscellaneous
• 5.1: context-filter dialog
• 5.2: mocks-v3 dialog
• 5.3: suggestions dialog V3
• 5.4: unexpected-file dialog
• 6: Video use cases
• 6.1: TV search use case
• 6.1.1: Dialog configuration
• 6.1.2: TV search plugin
• 6.1.3: TV search resources
• 6.1.4: NLP configuration by OB
• 6.2: TV display use case
• 6.2.1: Dialog configuration
• 6.2.2: TV display plugin
• 6.2.3: TV display resources
• 6.2.4: NLP configuration by OB
• 6.3: TV content get info use case
• 6.3.1: Dialog configuration
• 6.3.2: TV content get info plugin
• 6.3.3: TV content get info resources
• 6.3.4: NLP configuration by OB
• 6.4: TV move backwards use case
• 6.4.1: Dialog configuration
• 6.4.2: TV move backwards resources
• 6.4.3: NLP configuration by OB
• 6.5: TV move forwards use case
• 6.5.1: Dialog configuration
• 6.5.2: TV move forwards resources
• 6.5.3: NLP configuration by OB
• 6.6: TV VOD EPG information use case
• 6.6.1: Dialog configuration
• 6.6.2: TV VOD EPG information plugin
• 6.6.3: TV VOD EPG information resources
• 6.6.4: NLP configuration by OB
• 6.7: TV none use case
• 6.7.1: Dialog configuration
• 6.7.2: TV None plugin
• 6.7.3: TV none resources
• 6.7.4: NLP configuration by OB
• 6.8: Audiovisual App Opening use case
• 6.8.1: Dialog configuration
• 6.8.2: Audiovisual App Opening resources
• 6.8.3: NLP configuration by OB
• 6.9: Change language use case
• 6.9.1: Dialog configuration
• 6.9.2: Change language resources
• 6.9.3: NLP configuration by OB
• 6.10: Section Show
• 6.10.1: Dialog configuration
• 6.10.2: Section Show resources
• 6.10.3: NLP configuration by OB
• 6.11: Subtitles remove use case
• 6.11.1: Dialog configuration
• 6.11.2: Subtitles remove resources
• 6.11.3: NLP configuration by OB
• 6.12: Global resources for TV use cases
• 6.13: Legacy Video API for Spain
• 6.14: Adapter request-response model v1 to v3
• 7: AI use cases
• 7.1: TV LLM Conversational None UC
• 7.1.1: Dialog configuration
• 7.1.2: AI configuration by OB
• 7.2: TV LLM Conversational Search UC
• 7.2.1: tv-conversational-search-dialog
• 7.2.2: TV Conversational Search plugin
• 7.2.3: TV Conversational Search UC resources
• 7.2.4: AI configuration by OB
• 7.3: TV LLM Recommend UC
• 7.3.1: Dialog configuration
• 7.3.2: TV Recommend plugin
• 7.3.3: TV LLM Recommend UC resources
• 7.3.4: AI configuration by OB
• 7.4: TV LLM Search UC
• 7.4.1: Dialog configuration
• 7.4.2: TV Retrieve plugin for LLM Search UC
• 7.4.3: TV LLM Search UC resources
• 7.4.4: AI configuration by OB
• 7.5: TV LLM Triage UC
• 7.5.1: AI configuration by OB
• 7.6: TV Custom Recommendation UC
• 7.6.1: Dialog configuration
• 7.6.2: TV Custom Recommendation resources
• 7.6.3: NLP configuration by OB
• 7.6.4: NLP configuration by OB
• 8: Use cases for testing Aura
• 8.1: handover-genesys dialogs

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;

1 - Authentication dialogs

Global authentication dialogs

Global authentication dialogs include:

• Linking dialogs:
  • account-linking dialog
  • get-oauth-url dialog
  • account-remove dialog
  • seamless-account-remove dialog
• onboarding-whatsapp dialog
• whatsapp-otp-login dialog
• whatsapp-logout dialog

1.1 - account-linking dialog

account-linking dialog

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

1.2 - get-oauth-url dialog

get-oauth-url dialog

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.

1.3 - account-remove dialog

account-remove dialog

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.

1.4 - seamless-account-remove dialog

seamless-account-remove dialog

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.

1.5 - onboarding-whatsapp dialog

onboarding-whatsapp dialog

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.

1.6 - whatsapp-otp-login dialog

whatsapp-otp-login dialog

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:

1.7 - whatsapp-logout dialog

whatsapp-logout dialog

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.

2 - Conversational dialog

Conversational dialog

Introduction

The conversational-dialog allows users to interact with an LLM with a predefined prompt.

This prompt should return a json formatted object to be mapped in a standard Aiwi response message.

Specific configuration

The conversational-dialog is designed to handle user’s requests using LLMs in ATRIA.

Currently, this dialog is available for Aura channelData V1 version and can only be used for the channel AIWI.

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

    {
      "name": "conversational",
      "dialogs": [
        {
          "id": "conversational-dialog",
          "allowAnonymous": true,
          "triggerConditions": [
            {
              "intent": "None"
            }
          ],
          "bypass": {
            "duration": 30,
            "payloadName": "conversational",
            "initialData": {},
            "recognizersEnabled": false,
            "recognizersBreakIntents": {}
          }
        }
      ]
    }

Specific values

Environment variables

Configuration by channel

From Prince’s release onwards, the configuration of applicationId and presetId per channel and intent has been added to the channel model.

For this use case, the required specific configuration per channel is set below (added dialogs section under atria property at Main-Recognizer-Video-Triage-29855):

{
  "atria": {
    "dialogs":{
      "None": {
        "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
        "presetId": "ef3d0603-3fef-4109-a577-0ab92f9060df"
      }
    }
  }
}

Specific values by channel

3 - generic-ai-dialog

Aura bot generic-ai-dialog

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.

3.1 - Generic AI Dialog v1

Aura Bot generic-ai-dialog-v1

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

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.

3.2 - Generic AI Dialog v3

Aura Bot generic-ai-dialog-v3

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

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

4 - generic-dialog

Aura bot generic-dialog

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.

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!

4.1 - generic-dialog v1

Aura Bot generic-dialog 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.

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:

1. 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.

2. 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.

4.2 - generic-dialog-v3

Aura Bot generic-dialog-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

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

5 - Miscellaneous

Aura global dialogs: miscellaneous

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.

5.1 - context-filter dialog

context-filter 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
            }
        }
    ]

5.2 - mocks-v3 dialog

mocks-v3 dialog

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:

Environment variables

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.

5.3 - suggestions dialog V3

suggestions dialog v3

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:

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

5.4 - unexpected-file dialog

unexpected-file dialog

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

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

6 - Video use cases

Aura video use cases

Aura global video use cases provide different experiences to Telefónica customers for video services. Those video services could be provided by two platforms (BoB, for Spain or GVP, currently in Brazil) and through different channels, like Set-Top-Box, mobile apps or Movistar Home.

Experiences provided by Aura video use cases are related to searching or playing TV content, TV channels tuning, TV program guide information, reproduction control (move forwards/back, pause, resume, etc.), menu navigation, language and subtitles changing, actions to control (switch on/off, move channels up/down, mute/unmute, volume up/down) and more.

Those use cases are currently available in Spain legacy video platform for MH, STB and MP channels, but from now on, Aura Global Team will progressively migrate and adapt them in three ways:

1. Use cases will be migrated to a new Aura Platform component called Complex Logic Framework
2. Use cases will be adapted to normalized Aura v3 request-response model
3. Use cases will be adapted to use Video Contents normalized Kernel API

ℹ️ The objective and focus of all the documentation you can find here is for normalized Aura Global Video use cases (v3).

Access the left menu and discover the available video global experiences.

In addition, related with video plugins, there is a Postman collection available in Video Contents Kernel API.

6.1 - TV search use case

TV search use case

Introduction

The TV search use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura for TV content using a vocal interface.

Find additional information in following the documents:

• Discover the TV search specifications and the particularities of the use case development.
• Learn how to configure the generic-dialog for TV search use case.
• Access to the TV search plugin.
• Discover which are the resources used by the TV search use case.
• Find out the NLP configuration for each OB for the TV search use case.

Specifications

Kernel API

In order to resolve the user’s search request, Aura uses Video Contents normalized Kernel API.

Request-response model

TV search use case is adapted to the new request-response normalized model v3.

Available channels

Once TV search v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Search features

Currently, the normalized TV search use case includes basic search features and smart answers for entertainment content:

• Search by title
• Search by genre (movie, series, documentaries, programs, short films and games)
• Search by subgenre (action, scare, love, etc)
• Search by actor or director

In addition to these search features, the use case includes a contingency or fallback search mode used in case the Video Contents API does not provide any answer to Aura request. The contingency or fallback search mode could be deactivated by configuration.

🆕 As a novelty in the current release, the use case is able to provide the users with smart answers features, meaning that the entities included in the user’s requests can be included in the answer.

Therefore, the answer could be of this type: “That’s what I’ve found about [$title, $participant, $genre, $subgenre]

For example:

• The user asks for a specific title: “Play a film starring Brad Pitt”
• In previous versions, Aura sends the content provided by the API as “That’s what I’ve found for you”
• Now, the entity can be included in the answer, giving the user a most personalized answer: “That’s what I’ve found about Brad Pitt”

Current limitations

Currently, the TV search use case does not include these features:

• Request for a specific season o episode of a TV Series.
• Search content from third-parties (content must belong to Aura’s catalog).
• Search including temporary entities or time intervals.
• Search sport content based on entities.

Use case development

The TV search use case development includes these components:

Understanding features

• TV search use case intent: intent.tv.search

• TV search use case entities:

⚠️ Other entities in the user’s request are not taken into account in the searching process.

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect her intention.
• TV catalog in order to understand TV content (titles, actors, director) in the user’s utterance and detect them as Aura entities.
• Other content like genre or subgenre.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV search is built over the generic-dialog-v3.

  • Check the section Configuration of the generic-dialog for TV search use case in order to know the required configuration for the TV search experience.

• CLF Plugin:

  Complex Logic Framework is used for the recognition of the user’s request.

  • Check here the TV search plugin.

6.1.1 - Dialog configuration

Configuration of the generic-dialog for TV search use case

Specific configuration

The TV search use case is triggered by the generic-dialog-v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.search",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true,
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

6.1.2 - TV search plugin

TV search plugin

Introduction

The TV search plugin resolves the request from a user searching a video content.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error the resource returned is: tv:video.model-validation.request.error.

Filter invalid entities

The TV search plugin executes the step for entities validation listed below and prepares data before resolving the request:

1. Check that season/episode entity contains a number. In other case, it removes this entity.

Entertainment Search

The search of video content is based in the received entities.

The search stage follows the following steps:

Build the search_query param

The search builds a search_query param using label values of entities to prioritize the searched video content. If the label value is null for an entity, then the canon value is used.

Entities used to search are grouped by:

• Title entities: ent.audiovisual_documental_title, ent.audiovisual_film_title, ent.audiovisual_tvseries_title and ent.audiovisual_tvshows_title
• Participant entities: ent.audiovisual_actor and ent.audiovisual_director
• Genre entities: ent.audiovisual_genre and ent.audiovisual_subgenre

The priority to search using these entities is described as follows:

1. If there are title entities and other entities, then the search_query parameter is built only using title entities.
   • For instance: title: ("Matrix" OR "La princesa prometida")
2. If there are participant entities and other entities, then the search_query parameter is built only using participant entities.
   • All entities (ent.audiovisual_actor and ent.audiovisual_director) are used for fields actor and director.
   • For instance: actor: ("Tom Cruise" OR "Martin Scorsese") OR director: ("Tom Cruise" OR "Martin Scorsese")
3. If there are genre entities and other entities, then the search_query parameter is built only using genre entities.
   • The ent.audiovisual_genre is used with the field content_category and the ent.audiovisual_subgenre with field genre.
   • For instance: content_category: ("MOV" OR "SER" OR "DOC") AND genre: ("TE" OR "AC")
4. If there are not any entities allowed, then a query param to search is not built.

With this prioritization, the system builds a search_query param that will be used to call the API video query for searching purposes.

API video query

After preparing the search_query parameter, we will make a query to the Telefonica Kernel video API by searching through all the possible fields with the remaining words. To make this API call, several parameters are needed, which are described below:

• user_id: Input data[aura_user][user_id]
• administrative_number: Input data[app_context][user][account_number]
• access_token: Input data[aura_user][access_token]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]
• catalog_types: List of allowed catalog types. The value can now be a list of catalog types provided by the device, as long as the values are one of the following predefined identifiers: VOD, LIVE, L7D, LCH, LSR.
• search_query: String with a custom search query based in the received entities.
• show_series: series.
• profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in certain cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem we should send this field only when input data has this value.
• commercialization_types: List made by SVOD.
• max_quality: Input data[app_context][device][max_quality]

Search response

When performing a search, the following possible scenarios can occur for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error.

b. Receive no results at all. Then, it executes the contingency search if it isn’t disabled by configuration. If it is disabled by configuration, the returned resource is tv:video.search.no-results.

c. Receive a single result by searching for one title entity. The returned resource is tv:video.search.by-title.simple-result and params with the value of the title searched for.

d. Receive several results by searching for one title entity. The returned resource is tv:video.search.by-title.multiple-results and params with the value of the title searched for.

e. Receive a single result by searching for one actor/director entity. The returned resource is tv:video.search.by-participant.simple-result and params with the value of the participant searched for.

f. Receive several results by searching for one actor/director entity. The returned resource is tv:video.search.by-participant.multiple-results and params with the value of the participant searched for.

g. Receive a single result by searching for one genre entity. The returned resource is tv:video.search.by-genre.simple-result and params with the value of the genre searched for.

h. Receive several results by searching for one genre entity. The returned resource is tv:video.search.by-genre.multiple-results and params with the value of the genre searched for.

i. Receive a single result by searching for one genre and one subgenre entity. The returned resource is tv:video.search.by-subgenre.simple-result and params with the value of the genre and subgenre searched for.

j. Receive several results by searching for one genre and one subgenre entity. The returned resource is tv:video.search.by-subgenre.multiple-results and params with the value of the genre and subgenre searched for.

k. Receive a single result in all other cases. The returned resource is tv:video.search.by-default.simple-result.

l. Receive several results in all other cases. The returned resource is tv:video.search.by-default.multiple-results.

Contingency search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

When a request is made by the user, it is possible to find certain words with no real value for Aura, so the system is not able to redirect them to obtain a response. For this reason, a list of forbidden words known as “ignore-words” will be declared, which will be eliminated.

The first step is to transform the entire utterance received as input to lowercase, removing all non-alphanumeric characters and separators. Once the utterance has been normalized, the words that belong to the list of “ignore-words” are eliminated.

This list is declared in a resource file called normalizer_rules.json. This file can be found in the following path: src.aura_clf_video.resources.[language].normalizer_rules.json Where [language] must be replaced by each language, for example: es-es.

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

• Normalizer rules structure It is a dictionary where all the items are declared in a list as shown below:

  {
    "ignore_items": [
      "ignore item 1",
      "ignore item 2"
    ]
  }
  

• Validation of resource content
  The normalization is done sequentially, a previous rule cannot affect a succeeding one.

  For example:

  • The utterance is “ok aura some”.
  • We define “aura” and also “ok aura” in the “ignore-words” list.
  • If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
  • In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.search.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

• user_id: Input data[aura_user][user_id]
• administrative_number: Input data[app_context][user][account_number]
• access_token: Input data[aura_user][access_token]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]
• catalog_types: List of allowed catalog types. The value can now be a list of catalog types provided by the device, as long as the values are one of the following predefined identifiers: VOD, LIVE, L7D, LCH, LSR.
• search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
• show_series: series.
• profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
• commercialization_types: List made by SVOD.
• max_quality: Input data[app_context][device][max_quality]
• current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.search.contingency.no-results

c. Receive a single result. The returned resource is tv:video.search.contingency.single-result

d. Receive several results. The returned resource is tv:video.search.contingency.multiple-results

Response

The response follows this response schema.

Where:

• intent: input intent.

• entities: input entities.

• result_intent: This field is always MEDIA.SEARCH because it is the response associated to this domain.

• resources: List of response resources that includes three main parameters:

  • type: Type of the response resource.
  • name: Name of the response resource. Example: tv:video.search.contingency.single-result
  • params: This field returns any required parameter in the resource.

• payload: Information provided by the Kernel API, when we make the search request. If we receive a response. This field includes the following parameters:

  • type: The value of this field depends on the type of data included in the field data (info returned by the API):
    • If it is a value: details
    • If it is a list: content_list
  • data: It returns the information provided by the Kernel API.

• status: Final status request. this field includes field the following parameters:

  • code: Status code.
  • message: Status message, which describes the status code.
  • params: Parameter that sends details of status. This field does not appear if it is empty.

• actions: Actions to follow with the result of request.

• conditions: Condition for the actions to be applied.

6.1.3 - TV search resources

TV search use case resources

Introduction

The TV search use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case: tv.search

Specific resources for the use case: tv.search

The resources associated to the TV search plugin are defined below:

6.1.4 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV search use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.search

Entities

• ent.audiovisual_actor
• ent.audiovisual_director
• ent.audiovisual_documental_title
• ent.audiovisual_film_title
• ent.audiovisual_genre
• ent.audiovisual_subgenre
• ent.audiovisual_tvseries_title
• ent.audiovisual_tvshow_title

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• CluRecognizerWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

Spain

The TV search use case is available for three channels: Movistar Plus, Movistar Home and STB.

Intent

intent.tv.search

Entities

• ent.audiovisual_actor
• ent.audiovisual_best
• ent.audiovisual_director
• ent.audiovisual_documental_title
• ent.audiovisual_film_title
• ent.audiovisual_genre
• ent.audiovisual_most_watched
• ent.audiovisual_releases
• ent.audiovisual_sports
• ent.audiovisual_sports_circuit
• ent.audiovisual_sports_player_driver
• ent.audiovisual_sports_player_rider
• ent.audiovisual_sports_season
• ent.audiovisual_sports_season_motor
• ent.audiovisual_sports_team
• ent.audiovisual_sports_unit
• ent.audiovisual_subgenre
• ent.audiovisual_tv_episode_number
• ent.audiovisual_tv_season_number
• ent.audiovisual_tvseries_title
• ent.audiovisual_tvshow_title
• ent.device_mobile
• ent.device_tv
• ent.time_instant
• ent.time_interval
• ent.time_interval_future
• ent.time_interval_past

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• CluRecognizerWrapper
• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.json files can be checked here for each channel:

• Movistar Plus: https://github.com/Telefonica/aura-nlpdata-es/blob/master/data/es-es/mp/pipeline.json
• Movistar Home: https://github.com/Telefonica/aura-nlpdata-es/blob/master/data/es-es/mh/pipeline.json
• STB: https://github.com/Telefonica/aura-nlpdata-es/blob/master/data/es-es/stb/pipeline.json

6.2 - TV display use case

TV display use case

Introduction

The TV display use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura for a TV channel or other entities using a vocal interface.

Find additional information in following the documents:

• Discover the TV display specifications and the particularities of the use case development.
• Learn how to configure the generic-dialog for TV display use case.
• Access to the TV display plugin.
• Discover which are the resources used by the TV display use case.
• Find out the NLP configuration for each OB for the TV display use case.

Specifications

Kernel API

In order to resolve the user’s display request, Aura uses Video Contents normalized Kernel API.

Request-response model

TV display use case is adapted to the new request-response normalized model v3.

Available channels

Once TV display v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Display features

Currently, the normalized TV display use case includes the following display features:

• Display by channel (both for Brazil and Spain OBs)
• Display by content: title, genre, subgenre, actor or director (for Spain OB)

Therefore, the answer could be of this type: “This is what they are broadcasting now on that channel”

Use case development

The TV display use case development includes these components:

Understanding features

• TV display use case intent: intent.tv.display

• TV display use case entities: Entities vary across the OBs where this experience is available: Check NLP configuration by OB.

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect her intention.
• TV catalog in order to understand TV content (channels, titles, genres, subgenres, actors, directors) in the user’s utterance and detect them as Aura entities.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV display is built over the generic-dialog-v3.

  • Check the section Configuration of the generic-dialog for TV display use case in order to know the required configuration for the TV display experience.

• CLF Plugin:

  Complex Logic Framework is used for the recognition of the user’s request.

  • Check here the TV display plugin.

6.2.1 - Dialog configuration

Configuration of the generic-dialog for TV display use case

Specific configuration

The TV display use case is triggered by the generic-dialog-v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.display",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

6.2.2 - TV display plugin

TV display plugin

Introduction

The TV display plugin resolves the request from a user displaying a channel or content.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Display channel or content

The display channel or content is based in the received entities.

The display stage follows the steps set below:

Build the search_query param

The display plugin builds a search_query param using label values of entities to prioritize the searched channel content or video content. If the label value is null for an entity, then the canon value is used.

Entities used to search are grouped by:

• Channel entities: ent.audiovisual_channel
• Title entities: ent.audiovisual_documental_title, ent.audiovisual_film_title, ent.audiovisual_tvseries_title and ent.audiovisual_tvshow_title
• Participant entities: ent.audiovisual_actor and ent.audiovisual_director
• Genre entities: ent.audiovisual_genre and ent.audiovisual_subgenre

The priority to search using these entities is described as follows:

1. If there are channel entities and other entities, then the search_query parameter is built only using the first channel entity.
   • For instance: channel_name: "La 1"
2. If there are title entities and other entities, then the search_query parameter is built only using title entities.
   • For instance: title: ("Matrix" OR "La princesa prometida")
3. If there are participant entities and other entities, then the search_query parameter is built only using participant entities.
   • All entities (ent.audiovisual_actor and ent.audiovisual_director) are used for fields actor and director.
   • For instance: actor: ("Tom Cruise" OR "Martin Scorsese") OR director: ("Tom Cruise" OR "Martin Scorsese")
4. If there are genre entities and other entities, then the search_query parameter is built only using genre entities.
   • The ent.audiovisual_genre is used with the field content_category and the ent.audiovisual_subgenre with field genre.
   • For instance: content_category: ("MOV" OR "SER" OR "DOC") AND genre: ("Terror" OR "Acción")
5. If there are not any entities allowed, then a query param to search is not built.

With this prioritization, the system builds a search_query param that will be used to call the API video query for searching purposes.

Video query API

After preparing the search_query parameter, we will make a query to Video Contents normalized Kernel API by searching through all the possible fields with the remaining words.

To make this API call, several parameters are needed, which are described below:

• user_id: Input data[aura_user][user_id]
• administrative_number: Input data[app_context][user][account_number]
• access_token: Input data[aura_user][access_token]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]
• catalog_types: use LIVE value if there are channel entities, else use VOD,LIVE,L7D value for title entities, participant entities or genre entities.
• search_query: String with a custom search query based in the received entities.
• show_series: series.
• commercialization_types: List made by SVOD.
• max_quality: Input data[app_context][device][max_quality]
• order: personal
• commercial_offer: Input data[app_context][user][profile] if exists. Otherwise, do not use this param.
• live_at: if there are channel entities use UTC current time at which the request is made. Otherwise, do not use this param.
• profile: Input data[app_context][user][video_profile_name] if exists. Otherwise, do not use this param.
• current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

The fields current_region and profile may not be implemented in certain cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send these fields only when input data has this value.

Display response

When a user requests for displaying a channel, the following possible scenarios can occur for the response:

a. Receive no results at all. Then, it executes the contingency search.

b. Receive content with channel info. The returned resource is tv:video.display.by-channel.single-result

c. Receive content with channel info has already been broadcast or recieve a video content. The returned resource is video.display.by-default.single-result

d. Receive content with channel info that has not been broadcast yet or the content does not have enough information to be played. The returned resource is video.display.by-default.detail-result

e. Receive more than one type of content with channel info or video content. The returned resource is tv:video.display.by-default.multiple-results

f. Receive an API error. The returned resource is tv:video.api.answer.error

Contingency search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

When a request is made by the user, it is possible to find certain words with no real value for Aura, so the system is not able to redirect them to obtain a response. For this reason, a list of forbidden words known as “ignore-words” will be declared, which will be eliminated.

The first step is to transform the entire utterance received as input to lowercase, removing all non-alphanumeric characters and separators. Once the utterance has been normalized, the words that belong to the list of “ignore-words” are eliminated.

This list is declared in a resource file called normalizer_rules.json. This file can be found in the following path: src.aura_clf_video.resources.[language].normalizer_rules.json Where [language] must be replaced by each language, for example: es-es.

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

• Normalizer rules structure It is a dictionary where all the items are declared in a list as shown below:

  {
    "ignore_items": [
      "ignore item 1",
      "ignore item 2"
    ]
  }
  

• Validation of resource content
  The normalization is done sequentially, a previous rule cannot affect a succeeding one.

  For example:

  • The utterance is “ok aura some”.
  • We define “aura” and also “ok aura” in the “ignore-words” list.
  • If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
  • In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.display.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

• user_id: Input data[aura_user][user_id]
• administrative_number: Input data[app_context][user][account_number]
• access_token: Input data[aura_user][access_token]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]
• catalog_types: List that is made by VOD, LIVE and L7D.
• search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
• show_series: series.
• profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
• commercialization_types: List made by SVOD.
• max_quality: Input data[app_context][device][max_quality]
• order: personal
• current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.display.contingency.no-results

c. Receive a single result. The returned resource is tv:video.display.contingency.single-result

d. Receive several results. The returned resource is tv:video.display.contingency.multiple-results

Response

The response follows this response schema.

Where:

• intent: input intent.

• entities: input entities.

• result_intent: This field is always MEDIA.SEARCH except when the resource is:

  • video.display.by-channel.single-result, then the field value is CHANNEL.PLAY
  • video.display.by-default.single-result, then the field value is CONTENT.PLAY

• resources: List of response resources that includes three main parameters:

  • type: Type of the response resource.
  • name: Name of the response resource. Example: tv:video.display.by-channel.single-result
  • params: This field returns any required parameter in the resource.

• payload: Information provided by the Kernel API, when we make the display request. If we receive a response, this field includes the following parameters:

  • type: The value of this field depends on the type of data included in the field data (info returned by the API):
    • If it is a value: details
    • If it is a list: content_list
  • data: It returns the information provided by the Kernel API.

• status: Final status request. This field includes the following parameters:

  • code: Status code.
  • message: Status message, which describes the status code.
  • params: Parameter that sends details of status. This field does not appear if it is empty.

• actions: Actions to follow with the result of request. This plugin could include the following actions:

  • REMOTEON.ZAPTO: The target for this action is stb and its parameters are:
    • channelId, channelNumber and deviceId when we have the resource tv:video.display.by-channel.single-result
  • REMOTEON.PLAYTO: The target for this action is stb and its parameters are:
    • contentId, deviceId, liveProgramId and catalogType when we have the resource video.display.by-default.single-result and content has already been broadcast.
    • contentId, deviceId and catalogType when we have the resource video.display.by-default.single-result and content is a video content.
  • MAKE_SOUND: The target for this action is channel and its unique parameter is sound with the value:
    • positive when we have the resource tv:video.display.by-channel.single-result, video.display.by-default.single-result, video.display.by-default.detail-result, tv:video.display.by-default.multiple-results, tv:video.display.contingency.single-result, tv:video.display.contingency.multiple-results
    • negative when we have the resource tv:video.display.contingency.no-results and tv:video.api.answer.error.

• conditions: Condition for the actions to be applied.

6.2.3 - TV display resources

TV display use case resources

Introduction

The TV display use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case: tv.display

Specific resources for the use case: tv.display

The resources associated to the TV display plugin are defined below:

6.2.4 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the normalized TV display use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.display

Entities

| ent.audiovisual_channel | “Quiero ver La 1” |

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• CluRecognizerWrapper
• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

Spain

The TV display use case is available for three channels: Movistar Plus, Movistar Home and STB.

Intent

intent.tv.display

Entities

| ent.audiovisual_channel | “Quiero ver La 1” | | ent.audiovisual_*_title | “Ver Titanic” | | ent.audiovisual_subgenre | “Pon esta comedia” | | ent.audiovisual_genre | “Pon la película” | | ent.audiovisual_actor | “Quiero ver la peli de Brad Pitt” | | ent.audiovisual_director | “Ver el documental de Almodóvar” |

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• CluRecognizerWrapper
• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.json files can be checked here for each channel:

• Movistar Plus: https://github.com/Telefonica/aura-nlpdata-es/blob/master/data/es-es/mp/pipeline.json
• Movistar Home: https://github.com/Telefonica/aura-nlpdata-es/blob/master/data/es-es/mh/pipeline.json
• STB: https://github.com/Telefonica/aura-nlpdata-es/blob/master/data/es-es/stb/pipeline.json

6.3 - TV content get info use case

TV content get info use case

Introduction

The TV content get info use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura for a TV channel information using a vocal interface.

Find additional information in following the documents:

• Discover the TV content get info specifications and the particularities of the use case development.
• Learn how to configure the generic dialog for TV content get info use case.
• Access to the TV content get info plugin.
• Discover which are the resources used by the TV content get info use case.
• Find out the NLP configuration for each OB for the TV content get info use case.

Specifications

Kernel API

In order to resolve the user’s request, Aura uses Video Contents normalized Kernel API.

Request-response model

TV content get info use case is adapted to the new request-response normalized model v3.

Available channels

Once TV content get info v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Currently, STB channels in ES are already available.

Display features

Currently, the normalized TV content get info use case includes basic get content information features for channels:

• Content get info by channel

Therefore, the answer could be of this type: “This is what they are broadcasting now on that channel”

Use case development

The TV content get info use case development includes these components:

Understanding features

• TV content get info use case intent: intent.tv.content_get_info

• TV content get info use case entities:

⚠️ Other entities in the user’s request are not taken into account in the get content info process.

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect her intention.
• TV catalog in order to understand TV content (channels) in the user’s utterance and detect them as Aura entities.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV content get info is built over the generic dialog v3.

  • Check the section Configuration of the generic dialog for TV content get info use case in order to know the required configuration for the TV content get info experience.

• CLF Plugin:

  Complex Logic Framework is used for the recognition of the user’s request.

  • Check here the TV content get info plugin.

6.3.1 - Dialog configuration

Configuration of the generic dialog for TV content get info use case

Specific configuration

The TV content get info use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.content_get_info",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

6.3.2 - TV content get info plugin

TV content get info plugin

Introduction

The TV content get info plugin resolves the request from a user getting information about channel.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Get content info about a channel

The content get info about a channel is based in the received entities.

The content get info stage follows the steps set below:

Build the search_query param

The content get info builds a search_query param using label values of first entity ent.audiovisual_channel to prioritize channels searching. If the label value is null for an entity, then the canon value is used.

Entity used to search is: ent.audiovisual_channel

The entity will be used as follows:

1. If there are channel entities and other entities, then the search_query parameter is built only using the first channel entity.
   • For instance: channel_name: "La 1"
2. If there are not entities allowed, then a query param to content get info is not built.

With this prioritization, the system builds a search_query param that will be used to call the video query API for searching purposes.

Video query API

After preparing the search_query parameter, we will make a query to Video Contents normalized Kernel API by searching through all the possible fields with the remaining words.

To make this API call, several parameters are needed, which are described below:

• user_id: Input data[aura_user][user_id]
• administrative_number: Input data[app_context][user][account_number]
• access_token: Input data[aura_user][access_token]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]
• catalog_types: LIVE.
• search_query: String with a custom search query based in the received entities.
• show_series: series.
• commercialization_types: List made by SVOD.
• max_quality: Input data[app_context][device][max_quality]
• order: personal
• commercial_offer: Input data[app_context][user][profile] if exists. Otherwise, do not use this param.
• live_at: UTC current time at which the request is made.
• profile: Input data[app_context][user][video_profile_name] if exists. Otherwise, do not use this param.
• current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

The fields current_region and profile may not be implemented in certain cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send these fields only when input data has this value.

Content get info response

When a user requests for getting content information about a channel, the following possible scenarios can occur for the response:

a. No content with channel info is received. The returned resource is tv:video.content-get-info.by-channel.no-results

b. Receive content with channel info. The returned resource is tv:video.content-get-info.by-channel.single-result

c. More than one type of content is received. The returned resource is tv:video.content-get-info.by-channel.multiple-results

d. The request does not contain any ent.audiovisual_channel entity. The returned resource is tv:video.content-get-info.by-channel.no-results

e. Receive an API error. The returned resource is tv:video.api.answer.error

Response

The response follows this response schema.

Where:

• intent: input intent.

• entities: input entities.

• result_intent: This field is always MEDIA.SEARCH.

• resources: List of response resources that includes three main parameters:

  • type: Type of the response resource.
  • name: Name of the response resource. Example: tv:video.content-get-info.by-channel.single-result
  • params: This field returns any required parameter in the resource.

• payload: Information provided by the Kernel API, when we make the content get info request. If we receive a response, this field includes the following parameters:

  • type: The value of this field depends on the type of data included in the field data (info returned by the API):
    • If it is a value: details
    • If it is a list: content_list
  • data: It returns the information provided by the Kernel API.

• status: Final status request. This field includes the following parameters:

  • code: Status code.
  • message: Status message, which describes the status code.
  • params: Parameter that sends details of status. This field does not appear if it is empty.

• actions: Actions to follow with the result of request. This plugin could include the following actions:

  • MAKE_SOUND: The target for this action is channel and its unique parameter is sound (with negative value assigned). This action is returned when we have the resource tv:video.content-get-info.by-channel.no-results

• conditions: Condition for the actions to be applied.

6.3.3 - TV content get info resources

TV content get info use case resources

The TV content get info use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case: tv.content_get_info

Specific resources for the use case: tv.content_get_info

The resources associated to the TV content get info plugin are defined below:

6.3.4 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV content get info use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.content_get_info

Entities

• ent.audiovisual_actor
• ent.audiovisual_actor
• ent.audiovisual_best
• ent.audiovisual_channel
• ent.audiovisual_director
• ent.audiovisual_documental_title
• ent.audiovisual_film_title
• ent.audiovisual_genre
• ent.audiovisual_most_watched
• ent.audiovisual_releases
• ent.audiovisual_sports
• ent.audiovisual_sports_circuit
• ent.audiovisual_sports_player_driver
• ent.audiovisual_sports_player_rider
• ent.audiovisual_sports_season
• ent.audiovisual_sports_season_motor
• ent.audiovisual_sports_team
• ent.audiovisual_sports_unit
• ent.audiovisual_subgenre
• ent.audiovisual_tv_episode_number
• ent.audiovisual_tv_season_number
• ent.audiovisual_tvseries_title
• ent.audiovisual_tvshow_title
• ent.device_mobile
• ent.device_tv
• ent.time_instant
• ent.time_interval
• ent.time_interval_future
• ent.time_interval_past

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.4 - TV move backwards use case

TV move backwards use case

Introduction

The TV move backwards use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to move the content backwards on the TV using a vocal interface.

Find additional information in following the documents:

• Learn how to configure the generic dialog for TV move backwards use case.
• Discover which are the resources used by the TV move backwards use case.
• Find out the NLP configuration for each OB for the TV move backwards use case.

Specifications

Request-response model

TV move backwards use case is adapted to the new request-response normalized model v3.

Available channels

Once TV move backwards v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Currently, STB channel in ES is available for channelData V1. And channelData V3 is suitable for STB in Brazil with time entity recognition: ent.time_length_hour.

Display features

Currently, the normalized TV move backwards use case includes basic move backwards features for some entities:

• Move the TV content backwards
• Move backwards by specifying the desired time

This UC also includes specific verbs without entities. For AP repository the key verbs are: “retroceder”, “retornar” and “rebobinar”. For Brazil, they are “recuar” and “retroceder”.

Therefore, the answer could be of this type: “Okay, I’ll rewind the TV content.”

Use case development

The TV move backwards use case development includes these components:

Understanding features

• TV move backwards use case intent: intent.tv.move_backwards

• TV move backwards use case entities:

⚠️ Other entities in the user’s request are not taken into account in the move backwards process.

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect the user’s intention.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV move backwards is built over the generic dialog v3.

  • Check the section Configuration of the generic dialog for TV move backwards use case in order to know the required configuration for the TV move backwards experience.

6.4.1 - Dialog configuration

Configuration of the generic dialog for TV move backwards use case

Specific configuration

The TV move backwards use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

• Configuration for Brazil OB in STB channel. In this configuration, no default value is defined, as the STB device will resolve it when receiving an empty value in the parameter levels. A new entity is now recognized: ent.time_length_hour. Additional recognition was required by the aura-bot in order to obtain the total number of seconds to be returned in the parameter levels. To obtain that convertion into seconds, a new function has been created in utiles called: getSecondsLevelsWithTimerRecognizer.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_backwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveBackwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData",
                        "genericUtils",
                        "configuration"
                    ],
                    "algorithm": "return new Promise(async (resolve, reject) => { try { const params = { levels: await genericUtils.getSecondsLevelsWithTimerRecognizer(currentIntent, configuration) }; persistentData.dialogData.actionParams['SEND_KEY'] = params; resolve(); } catch (error) { reject(error); } });"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

6.4.2 - TV move backwards resources

TV move backwards use case resources

The TV move backwards use case will use two different types of resources:

• Aura Platform global resources
• Common resources for video use cases

6.4.3 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV move backwards use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.move_backwards

Entities

• ent.audiovisual_genre
• ent.time_length_sec
• ent.time_length_min
• ent.time_length_hour
• ent.time_instant

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.5 - TV move forwards use case

TV move forwards use case

Introduction

The TV move forwards use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to move the content forwards on the TV using a vocal interface.

Find additional information in following the documents:

• Learn how to configure the generic dialog for TV move forwards use case.
• Discover which are the resources used by the TV move forwards use case.
• Find out the NLP configuration for each OB for the TV move forwards use case.

Specifications

Request-response model

TV move forwards use case is adapted to the new request-response normalized model v3.

Available channels

Once TV move forwards v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Currently, MH and STB channels in ES are already available for channelData V3 version and MP is available for channelData V1. But for these channels, time entity recognition: ent.time_length_hour is not yet available. It would be available for STB in Brazil.

Display features

Currently, the normalized TV move forwards use case includes basic move forwards features for some entities:

• Move the TV content forwards
• Move forwards by specifying the desired time

This UC also includes specific verbs without entities. For AP repository the key verbs are: “avanzar” and “adelantar”. For Brazil, they are “adiantar” and “avançar”.

Therefore, the answer could be of this type: “Ok, I’ll fast forward the content a little”

Use case development

The TV move forwards use case development includes these components:

Understanding features

• TV move forwards use case intent: intent.tv.move_forwards

• TV move forwards use case entities:

⚠️ Other entities in the user’s request are not taken into account in the move forwards process.

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect the user’s intention.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV move forwards is built over the generic dialog v3.

  • Check the section Configuration of the generic dialog for TV move forwards use case in order to know the required configuration for the TV move forwards experience.

6.5.1 - Dialog configuration

Configuration of the generic dialog for TV move forwards use case

Specific configuration

The TV move forwards use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

• Configuration for Spain OB in MP, MH and STB channels. In this configuration, there is still a default value of 60 seconds if no time entity is identified. Only the minutes and seconds entities are handled.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_forwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveForwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY",
                        "params": {
                            "keyCode": "MOVE_FORWARD",
                            "levels": "60"
                        }
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData"
                    ],
                    "algorithm": "currentIntent.entities.map((ent) => { if (!isNaN(ent.entity)) { persistentData.dialogData.actionParams.SEND_KEY = { levels: ent.type === 'ent.time_length_sec' ? Number(ent.entity) : Number(ent.entity) * 60}}})"
                }
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

• Configuration for Brazil OB in STB channel. In this configuration, no default value is defined, as the STB device will resolve it when receiving an empty value in the parameter levels. A new entity is now recognized: ent.time_length_hour. Additional recognition was required by the aura-bot in order to obtain the total number of seconds to be returned in the parameter levels. To obtain that convertion into seconds, a new function has been created in utiles called: getSecondsLevelsWithTimerRecognizer.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_forwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveForwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData",
                        "genericUtils",
                        "configuration"
                    ],
                    "algorithm": "return new Promise(async (resolve, reject) => { try { const params = { levels: await genericUtils.getSecondsLevelsWithTimerRecognizer(currentIntent, configuration) }; persistentData.dialogData.actionParams['SEND_KEY'] = params; resolve(); } catch (error) { reject(error); } });"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

6.5.2 - TV move forwards resources

TV move forwards use case resources

The TV move forwards use case will use two different types of resources:

• Aura Platform global resources
• Common resources for video use cases

6.5.3 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV move forwards use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.move_forwards

Entities

• ent.audiovisual_genre
• ent.time_length_sec
• ent.time_length_min
• ent.time_length_hour
• ent.time_instant

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.6 - TV VOD EPG information use case

TV VOD EPG information use case

Introduction

The TV VOD EPG information use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura about what they are watching on TV at that specific moment using a vocal interface. The use case answers with the name of the TV content being broadcasted.

• A user interacts with Aura through a normalized video channel
• She asks about the content currently playing: “What am I watching?”, “What’s on?”
• Aura recognizes the request and provides back to the channel the information required to answer the request

Find additional information in following the documents:

• Discover the TV VOD EPG information specifications and the particularities of the use case development.

• Learn how to configure the generic dialog for TV VOD EPG information use case.

• Find out the NLP configuration for each OB for the TV VOD EPG information use case.

Specifications

Kernel API

In order to resolve the user’s request, Aura uses Video Contents normalized Kernel API.

Request-response model

TV VOD EPG information use case is adapted to the new request-response normalized model v3.

Available channels

TV VOD EPG information use case could be available for any channel that implements normalized v3 request-response model including TV related data.

Currently, STB channels in BR are already available.

Display features

Currently, the normalized TV VOD EPG information use case includes basic VOD EPG information features for content:

• VOD EPG information by content

Therefore, the questions could be of this type: “What am I watching?” “Which actors are involved?”

Use case development

The TV VOD EPG information use case development includes these components:

Understanding features

• TV VOD EPG information use case intent: intent.tv-vod_epg_information

• TV VOD EPG information use case entities:

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect the user’s intention.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV VOD EPG information is built over the generic dialog v3.

  • Check the section Configuration of the generic dialog for TV VOD EPG information use case in order to know the required configuration for the TV VOD EPG information experience.

6.6.1 - Dialog configuration

Configuration of the generic dialog for TV VOD EPG information use case

Specific configuration

The TV VOD EPG information use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.vod_epg_information",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "payloadType" : "tv",
                "functions" : {
                    "params" : [
                        "currentIntent",
                        "persistentData"
                    ],
                    "algorithm" : "const entityType = currentIntent?.entities?.[0]?.type; switch (entityType) { case 'ent.device_tv': case 'ent.device_mobile': case 'ent.device_phone': persistentData.dialogData.dialogSetting.forcedIntentResult = { name: 'MEDIA.SHEET_TV', entities: [ { type: entityType, entity: currentIntent.entities?.[0]?.entity } ] }; break; default: persistentData.dialogData.dialogSetting.forcedIntentResult = { name: 'MEDIA.SHEET_SECOND_SCREEN', entities: [] }; break; }"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Specific values

6.6.2 - TV VOD EPG information plugin

TV VOD EPG information plugin

Introduction

The TV VOD EPG information plugin resolves the request from a user getting information about the TV content broadcasted in this specific moment

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Get VOD EPG information about a playing content

The VOD EPG information about a playing content is based in the catalog type and content id.

To retrieve content information stage follows the steps set below:

Video query API

We will make a query to Video Contents normalized Kernel API to retrieve content.

To make this API call, several parameters are needed, which are described below:

• user_id: Input data[aura_user][user_id]
• access_token: Input data[aura_user][access_token]
• catalog_type: Input data[app_context][playing][catalog_type] where “vod” is “VOD”, “l7d” and “record” is “L7D”, and “live” is “LIVE”.
• administrative_number: Input data[app_context][user][account_number]
• content_id: Input data[app_context][playing][content_id]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]

VOD EPG information response

When a user requests for getting playing EPG information about a specific content, the following possible scenarios can occur for the response:

a. Receive a content with the EPG information and the request contain devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.moreInfoTvDetail

b. Receive a content with the EPG information and the request does not contain any devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:carousel.info.contentDetail

c. Not received or not found in API any content with the EPG information and the request does not contain any devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.moreInfoTvNotAllowed

d. Not received or not found in API any content with the EPG information and the request contain devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.more_info.notAllowed

e. Receive an API error. The returned resource is tv:video.api.answer.error

Response

The response follows this response schema.

Where:

• intent: input intent.

• entities: input entities.

• result_intent: This field is always MEDIA.SHEET_TV except when the resource is tv:carousel.info.contentDetail or tv:tv.more_info.notAllowed. In this case this field is MEDIA.SHEET_SECOND_SCREEN.

• resources: List of response resources that includes three main parameters:

  • type: Type of the response resource.
  • name: Name of the response resource. Example: tv:tv.moreInfoTvDetail
  • params: This field returns any required parameter in the resource.

• payload: Information provided by the Kernel API, when we make the VOD EPG information request. For this case, If we receive a response, it is a value and then this field includes the following parameters:

  • type: details
  • data: It returns the information provided by the Kernel API.

• status: Final status request. This field includes the following parameters:

  • code: Status code.
  • message: Status message, which describes the status code.
  • params: Parameter that sends details of status. This field does not appear if it is empty.

• actions: Actions to follow with the result of request.

• conditions: Condition for the actions to be applied.

6.6.3 - TV VOD EPG information resources

TV VOD EPG information use case resources

The TV VOD EPG information use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case: tv.vod_egp_information

Specific resources for the use case: tv.vod_epg_information

The resources associated to the TV VOD EPG information plugin are defined below:

6.6.4 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV VOD EPG information use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.vod_epg_information

Entities

• ent.device_tv
• ent.device_mobile
• ent.device_phone

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• “ExactMatchRecognizerWrapper”
• “PygrapeGrammarWrapper”
• “EntityTaggerAdapterWrapper”

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.7 - TV none use case

TV none use case

Introduction

The TV none use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura using a vocal interface.

Find additional information in following the documents:

• Discover the TV none specifications and the particularities of the use case development.
• Learn how to configure the generic dialog for TV none use case.
• Access to the TV none plugin.
• Discover which are the resources used by the TV none use case.
• Find out the NLP configuration for each OB for the TV none use case.

Specifications

Kernel API

In order to resolve the user’s request, Aura uses Video Contents normalized Kernel API.

Request-response model

TV none use case is adapted to the new request-response normalized model v3.

Available channels

Once TV none v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Currently, STB channels in BR are already available.

Display features

Currently, the normalized TV none use case includes basic search features for content/channels:

• none search content/channels with user normalized utterance

Therefore, the answer could be any provided by the recognized intent: intent.tv.none

Use case development

The TV none use case development includes these components:

Understanding features

• TV none use case intent: intent.tv.none

• TV none use case entities: Ignore the entities for search content/channels, use normalized utterance for contigency search.

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect her intention.
• TV catalog in order to understand TV content (channels) in the user’s utterance and detect them as Aura entities.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  TV none is built over the generic dialog v3.

  • Check the section Configuration of the generic dialog for TV none use case in order to know the required configuration for the TV none experience.

• CLF Plugin:

  Complex Logic Framework is used for the recognition of the user’s request.

  • Check here the TV none plugin.

6.7.1 - Dialog configuration

Configuration of the generic dialog for TV none use case

Specific configuration

The TV none use case is triggered by the generic dialog v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.none",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Specific values

6.7.2 - TV None plugin

TV none plugin

Introduction

The TV none plugin resolves the request from a user getting information about channel.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Contingency Search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

When a request is made by the user, it is possible to find certain words with no real value for Aura, so the system is not able to redirect them to obtain a response. For this reason, a list of forbidden words known as “ignore-words” will be declared, which will be eliminated.

The first step is to transform the entire utterance received as input to lowercase, removing all non-alphanumeric characters and separators. Once the utterance has been normalized, the words that belong to the list of “ignore-words” are eliminated.

This list is declared in a resource file called normalizer_rules.json. This file can be found in the following path: src.aura_clf_video.resources.[language].normalizer_rules.json Where [language] must be replaced by each language, for example: es-es.

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

• Normalizer rules structure:
  It is a dictionary where all the items are declared in a list as shown below:

  {
    "ignore_items": [
      "ignore item 1",
      "ignore item 2"
    ]
  }
  

• Validation of resource content:
  The normalization is done sequentially, a previous rule cannot affect a succeeding one.

  For example:

  • The utterance is “ok aura some”.
  • We define “aura” and also “ok aura” in the “ignore-words” list.
  • If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
  • In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.search.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

• user_id: Input data[aura_user][user_id]
• administrative_number: Input data[app_context][user][account_number]
• access_token: Input data[aura_user][access_token]
• scopes: Input data[aura_user][scopes]
• purposes: Input data[aura_user][purposes]
• device_type: Input data[app_context][device][type]
• catalog_types: List that is made by VOD, LIVE and L7D.
• search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
• show_series: series.
• profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
• commercialization_types: List made by SVOD.
• max_quality: Input data[app_context][device][max_quality]
• order: personal
• current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.search.contingency.no-results

c. Receive a single result. The returned resource is tv:video.search.contingency.single-result

d. Receive several results. The returned resource is tv:video.search.contingency.multiple-results

Response

The response follows this response schema.

Where:

• intent: input intent.

• entities: input entities.

• result_intent: This field is always MEDIA.SEARCH because it is the response associated to this domain.

• resources: List of response resources that includes three main parameters:

  • type: Type of the response resource.
  • name: Name of the response resource. Example: tv:video.search.contingency.single-result
  • params: This field returns any required parameter in the resource.

• payload: Information provided by the Kernel API, when we make the search request. If we receive a response. This field includes the following parameters:

  • type: The value of this field depends on the type of data included in the field data (info returned by the API):
    • If it is a value: details
    • If it is a list: content_list
  • data: It returns the information provided by the Kernel API.

• status: Final status request. this field includes field the following parameters:

  • code: Status code.
  • message: Status message, which describes the status code.
  • params: Parameter that sends details of status. This field does not appear if it is empty.

• actions: Actions to follow with the result of request.

• conditions: Condition for the actions to be applied.

6.7.3 - TV none resources

TV none use case resources

The TV none use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case: tv.none

Specific resources for the use case: tv.none

The resources associated to the TV none plugin are defined below:

6.7.4 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV None use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.none

Entities

• No use specific entities to obtain results.

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• CluRecognizerWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.8 - Audiovisual App Opening use case

Audiovisual App Opening use case

Introduction

The Audiovisual App Opening use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to open different third-party apps that are considered audiovisual apps.

• A user interacts with Aura through a normalized video channel
• The user requests: “I want to put this <app> on the TV”, where <app> is a third-party app
• Aura recognizes the request and provides back to the channel the information required to open this app

For example:

• “Open Amazon Prime Video app”
• “Access TikTok”
• “Put Disney on TV”

Find additional information in the following documents:

• Discover the Audiovisual App Opening specifications and the particularities of the use case development.

• Learn how to configure the generic-dialog for Audiovisual App Opening use case.

• Discover the resources used by the Audiovisual App Opening use case

• Find out the NLP configuration for each OB for the Audiovisual App Opening use case.

Specifications

Kernel API

In order to resolve the user’s request, Aura uses Video Contents normalized Kernel API.

Request-response model

Audiovisual App Opening use case is adapted to the request-response normalized model v3.

Available channels

• STB (aura-nlpdata-br-stb)
• GVP (aura-nlpdata-ap)

Use case development

The Audiovisual App Opening use case development includes these components:

Understanding features

• Audiovisual App Opening use case intent: intent.tv.app_open

• Audiovisual App Opening use case entities:

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect its intention.
• TV catalog in order to understand audiovisual apps in the user’s utterance and detect them as Aura entities.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  Audiovisual App Opening is built over the generic-dialog-v3.

  • Check the section Configuration of the generic-dialog for Audiovisual App Opening use case in order to know the required configuration for the experience.

6.8.1 - Dialog configuration

Configuration of the generic-dialog for the Audiovisual App Opening use case

Specific configuration

The Audiovisual App Opening use case is triggered by the generic-dialog-v3.

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

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.app_open",
            "settings": {
                "locales": {
                    "error": [
                        "tv:video.section.not_available"
                    ]
                },
                "actions": [
                    {
                        "name": "GOTOAPP"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "sound": "positive",
                "needPlayingContent": false,
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

6.8.2 - Audiovisual App Opening resources

Audiovisual App Opening use case resources

Introduction

The Audiovisual App Opening use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case

Specific resources for the use case

The resources associated to the Audiovisual App Opening plugin are defined below:

6.8.3 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the Audiovisual App Opening use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.app_open

Entities

ent.audiovisual_app

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.9 - Change language use case

Change language use case

Introduction

The Change language use case is a global video experience designed and developed by Aura Global Team that allows Telefónica customers to change the language on TV.

• A user interacts with Aura through a normalized video channel

• The user requests: “Change subtitles to English”

• Aura recognizes the request and provides back to the channel the information required

For example:

• “Change subtitles to English”

• “Put the movie in the original version”

Find additional information in the following documents:

• Discover the Change language specifications and the particularities of the use case development.

• Learn how to configure the generic-dialog for Change language use case.

• Discover the resources used by the Change language use case.

• Find out the NLP configuration for each OB for the Change language use case.

Specifications

Kernel API

In order to resolve the user’s request, Aura uses Video Contents normalized Kernel API.

Request-response model

Change language use case is adapted to the request-response normalized model v3.

Available channels

• STB (aura-nlpdata-br-stb)
• GVP (aura-nlpdata-ap)

Use case development

The Change language use case development includes these components:

Understanding features

• Change language use case intent: intent.tv.language_change

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:
  Change language is built over the generic-dialog-v3. Check the section Configuration of the generic-dialog for Change language use case in order to know the required configuration for the experience.

6.9.1 - Dialog configuration

Configuration of the generic-dialog for Change language use case

Specific configuration

The Change language use case is triggered by the generic-dialog-v3.

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

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.language_change",
            "settings": {
                "locales": {
                    "error": [
                        "tv:tv.error.fpaOrCognitive"
                    ]
                },
                "actions": [
                    {
                        "name": "REMOTEON_AUDIO_SUBTITLES"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

6.9.2 - Change language resources

Change language use case resources

Introduction

The Change language use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases

6.9.3 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the TV Change language use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.language_change

Entities

No entities are handled for this intent.

Commands

Currently, the commands that trigger this intent are:

        "Audio em língua estrangeira",
        "Colocar legendas em espanhol",
        "Legendas em inglês",
        "Som em original"

Pipeline stages

Since there is a closed list of commands that could trigger this UC, the stage involved in its recognition is a deterministic one:

      "ExactMatchRecognizerWrapper",

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.10 - Section Show

Section Show use case

Introduction

The Section Show use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to open different sections and navigate through them.

• A user interacts with Aura through a normalized video channel
• The user requests: “I want to put this <section> on the TV”
• Aura recognizes the request and provides back to the channel the information required to open this section

For example:

• “Open aventura”
• “Access Kids”
• “Put films on TV”

Find additional information in the following documents:

• Discover the Section Show specifications and the particularities of the use case development.

• Learn how to configure the generic-dialog for Section Show use case.

• Discover the resources used by the Section Show use case.

• Find out the NLP configuration for each OB for the Section Show use case.

Specifications

Kernel API

In order to resolve the user’s request, Aura uses Video Contents normalized Kernel API.

Request-response model

Section Show use case is adapted to the request-response normalized model v3.

Available channels

• STB (aura-nlpdata-br-stb)
• GVP (aura-nlpdata-ap)

Use case development

The Section Show use case development includes these components:

Understanding features

• Section Show use case intent: intent.navigation.section_show

• Section Show use case entities:

In order to understand users’ requests (utterances), Aura is trained with:

• NLP expression to recognize the user’s utterance and detect its intention.
• TV catalog in order to understand audiovisual sections in the user’s utterance and detect them as Aura entities.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

• Aura Bot dialog:

  Section Show is built over the generic-dialog-v3.

  • Check the section Configuration of the generic-dialog for Section Show use case in order to know the required configuration for the experience.

6.10.1 - Dialog configuration

Configuration of the generic-dialog for Section Show use case

Specific configuration

The Section Show use case is triggered by the generic-dialog-v3.

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

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            {
                "intent": "intent.navigation.section_show",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "actions": [
                        {
                            "name": "NAVIGATION_SECTION_SHOW"
                        },
                        {
                            "name": "MAKE_SOUND"
                        }
                    ],
                    "sound": "positive",
                    "needPlayingContent": false,
                    "payloadType": "tv"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

6.10.2 - Section Show resources

Section Show use case resources

Introduction

The Section Show use case will use three different types of resources:

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case

Specific resources for the use case: tv.display

There are no specific resources for TV section show in V3. For v1, the resources associated are defined below:

6.10.3 - NLP configuration by OB

NLP configuration by OB

Introduction

The current document includes the configuration of the NLP model for the Section Show use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.navigation.section_show

Entities

ent.section

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

• PygrapeGrammarWrapper
• EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

6.11 - Subtitles remove use case

Subtitles remove use case

Introduction

The Subtitles remove use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to remove the subtitles.

• A user interacts with Aura through a normalized video channel
• The user requests: “Remove subtitles from the film”.
• Aura recognizes the request and provides back to the channel the information required

For example:

• “Remove subtitles from the movie”
• “Remove subtitles from this episode”

Find additional information in the following documents:

• Discover the Subtitles remove specifications and the particularities of the use case development.

• Learn how to configure the generic-dialog for Subtitles remove use case.

• Discover the resources used by the Subtitles remove use case.

• Find out the NLP configuration for each OB for the Subtitles remove use case.