Aura – build-response

Docs:

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

HTML5 attachments

Types of HTML attachments for Microsoft Bot Framework

Introduction

HTML attachments are a set of models whose main property is that the content of the elements to render are composed of HTML5 tags.

Aura’s HTML5 attachment template is used to send HTML5 snippets as a response template.

Custom Attachment Model

The custom attachment model contains a free format model.

Bot Framework Attachment Properties

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description
contentType	string	Content type name. Value: `application/vnd.telefonica.aura.html.custom`
content	AuraHtmlCustomContent	Model of the object where the HTML5 is
version	string	Attachment model version model
name	string	Attachment name (optional)

Aura HTML Custom Content

Property	Type	Description
containers	HTMLContainer[]	Array of containers where the HTML data is sent

HTML container

The HTML container contains an identifier and the content of HTML.

Content may be self-contained or referenced. If it is self-contained, the property data will contain the HTML. Otherwise, the property url-data will contain the URL to download the HTML.

Property	Type	Description
id	string	Identifier of tag where the content data will be placed.
encoded	EncodedFormat	How the HTML5 code is encoded in `data` properties. Values: `none`, `base64` or `zip`
data	string	HTML5 data.
url-data	string	URL where the HTML to assign to the given container id should be downloaded. The encoded field in this case is ignored.
content-type	string	Type of source: `html`, `javascript`, `css` or `json`. - If url-data has a URL, the AuraSDK will insert: . `<link href="[url-data]" rel="stylesheet" type="text/css" />` for css. . `<script src="[url-data]"></script>` for js. - If you do not use the Aura SDK, you must insert it manually. Default value: `html` Note: Javascript content cannot be unloaded once loaded into the browser, unless you reload the page or iframe.

Encoded Formats

Property	Description
none	The data is sent in HTML format
base64	The data is encoded in Base64
zip	The data is compressed in zip format

Example

{
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.html.custom",
      "version": "1.0.0",
      "content": {
        "containers": [
          {
            "id": "id-background",
            "url-data":"https://telepizza.com/containers/background?id=334"
          },
          {
            "id": "id-footer",
            "encoded": "base64",
            "data":"PGgyPkhUTUwgTGlua3M8L2gyPgo8cD5IVE1MIGxpbmtzIGFyZSBkZWZpbmVkIHdpdGggdGhlIGEgdGFnOjwvcD4KCjxhIGhyZWY9Imh0dHBzOi8vd3d3Lnczc2Nob29scy5jb20iPlRoaXMgaXMgYSBsaW5rPC9hPg=="
          }
        ]
      }
    }
  ]
}

Building Aura response through HTML5

To include HTML content in Aura’s responses, two conditions must be satisfied:

First, generate a response with an attachment whose content has the HTML code.
Second, the client must support the model of this type of attachments.

Check how to add attachments into messages in MS Bot Framework.

Generate Response with an HTML5 attachment

In order to generate responses with HTML content, it is necessary to follow the model created for it: Attachment Models.

To do this, simply generate an message attachment with the new model.

For example, if we want to send the word “Hello World” in HTML format:

Generate the necessary HTML code: Hello World! .
Include this code inside the model and assign a container to it, so that the client knows in which part of the webpage he must go. The assignation of a container is mandatory and needs the target Id of HTML element where the content will be rendered.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			data: "<span> Hello World! <span>"
		}
	     ]
	   }
	});

The content can be encoded to avoid problems with HTML code characters or to compress content if it is large. To inform the client of the type of encoding, use the encoded property.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			encoded: "base64",
			data: "PHNwYW4+IEhlbGxvIFdvcmxkISA8c3Bhbj4="
		}
	     ]
	   }
  });

Docs:

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

Aura response error messages

Sometimes, Aura could return some errors due to authentication or other APIs errors. This document describes the most common errors and how clients should handle them.

Unauthenticated error

In some channels that require authentication, Aura could return an unauthenticated error if the auraId is invalid. In this cases, the client should authenticate the user again and create a new auraId.

ChannelData v3 example:

        {
            "type": "message",
            "id": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000005",
            "timestamp": "2024-06-27T14:01:24.9377437Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "4VJyNMnfcQLHuvOAbXMLAK-fr"
            },
            "text": "Desculpe, não consegui verificar suas informações. Por favor, reinicie o aplicativo e tente novamente.",
            "inputHint": "acceptingInput",
            "channelData": {
                "correlator": "5b25cd4a-aa57-420d-9fb3-8db437df01cf",
                "version": "3",
                "status": {
                    "code": "ERROR.USER.UNAUTHENTICATED",
                    "message": "Invalid aura user",
                    "params": {
                        "auraId": "asdf"
                    }
                }
            },
            "replyToId": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000004"
        }

ChannelData v1 example:

        {
            "type": "message",
            "id": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000003",
            "timestamp": "2024-06-27T14:01:07.7998256Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "4VJyNMnfcQLHuvOAbXMLAK-fr"
            },
            "text": "Desculpe, não consegui verificar suas informações. Por favor, reinicie o aplicativo e tente novamente.",
            "speak": "Desculpe, não consegui verificar suas informações. Por favor, reinicie o aplicativo e tente novamente.",
            "inputHint": "acceptingInput",
            "channelData": {
                "hasMoreMessages": false,
                "correlator": "593a44ac-3974-472b-a7e4-610b3c760679",
                "Error": {
                    "code": "UNAUTHENTICATED",
                    "data": "invalidAuraId",
                    "message": "Invalid auraId"
                }
            },
            "replyToId": "4VJyNMnfcQLHuvOAbXMLAK-fr|0000002"
        }

Too many requests error

In some cases, certain APIs could return an error 429 due to quota limits or other reasons. In these scenarios, the client should wait the returned value of the parameter retryAfter and try again after this time.

ChannelData v3 example:

        {
            "type": "message",
            "id": "H2JRTbQW25d6Jyccs7PfEb-fr|0000007",
            "timestamp": "2024-06-27T14:08:26.8101993Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "H2JRTbQW25d6Jyccs7PfEb-fr"
            },
            "text": "Lo sentimos, ha ocurrido un error inesperado.",
            "inputHint": "acceptingInput",
            "channelData": {
                "correlator": "9df5cb1b-966c-4db4-9df8-e269c682a58b",
                "version": "3",
                "status": {
                    "code": "ERROR.API.TOO_MANY_REQUESTS",
                    "message": "Too many requests",
                    "params": {
                        "retryAfter": "10"
                    }
                }
            },
            "replyToId": "H2JRTbQW25d6Jyccs7PfEb-fr|0000006"
        }

ChannelData v1 example:

        {
            "type": "message",
            "id": "H2JRTbQW25d6Jyccs7PfEb-fr|0000009",
            "timestamp": "2024-06-27T14:08:45.5260908Z",
            "channelId": "directline",
            "from": {
                "id": "aura-bot-x",
                "name": "aura-bot-x"
            },
            "conversation": {
                "id": "H2JRTbQW25d6Jyccs7PfEb-fr"
            },
            "text": "Lo sentimos, ha ocurrido un error inesperado.",
            "speak": "Lo sentimos, ha ocurrido un error inesperado.",
            "inputHint": "acceptingInput",
            "channelData": {
                "hasMoreMessages": false,
                "correlator": "cd06e100-7783-46e8-8051-ee99e8b72f43",
                "Error": {
                    "code": "TOO_MANY_REQUESTS",
                    "data": {
                        "retryAfter": "10"
                    },
                    "message": "Too many requests"
                }
            },
            "replyToId": "H2JRTbQW25d6Jyccs7PfEb-fr|0000008"
        }

Docs:

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

Building Aura response in RCS channel

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

Introduction

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

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

Sending messages to clients

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

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

Sending a text message

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

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

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

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

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

Sending actions

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

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

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

More info in Handling user messages in RCS channel

Sending a dial action

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

Sending a location action

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

Sending an URL

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

Sending a prompt

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

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

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

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

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

Sending rich cards

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

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

Sending carousels

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

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

Docs:

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

Building Aura response in WhatsApp channel

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

Introduction

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

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

Specific POEditor resources for WhatsApp channel

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

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

Resources for Aura bridge errors

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

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

Resources for WhatsApp dialogs

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

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

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

Resources for buttons and lists

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

Rendering in WhatsApp channels

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

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

Rendering Aura response components

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

Configuration of Markdown type in the response

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

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

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

The succeeding sections show the specific processes for this configuration.

Modifications of Markdown format at channel level

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

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

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

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

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

⚠️ Be aware of the behavior:

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

Modification of Markdown format at dialog level

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

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

The interface is as follows:

export interface Whatsapp {
    ...

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

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

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

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

Docs:

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

Guidelines for building Aura response texts

When developing a use case, discover how to generate the texts included in each element of the response that Aura provides to its users. Texts are generated with POEditor and imported into Aura Bot.

Process at a glance

Enter
POEditor

. Log in POEditor
. Access your local POEditor project or create one

Generate
resources

. If required, generate a new resource, element associated with an specific text, for importing it into the bot

Edit
texts

. Search the specific text by library or resource name
. Edit the text with the message to be shown to the user

Import
locale files

. Install aura-locale-importer tool
. Upload locales to Aura Bot through this tool

Hot
swapping

. Make modifications available in between two releases through a hot swapping process

Introduction

When a new use case is developed, it is necessary to design Aura response for each step of the use case conversational flow. The answer, depending on the channel, can include text, cards, graphic resources, deeplinks, suggestions and actions.

The current section focuses on the text included in each element of the use case response.

Basic concepts

Get familiar with these basic concepts when designing your Aura response:

POEditor For the generation of the text included in each response element, Aura relies on POEditor.

POEditor offers a centralized localization tool to handle the different messages that the bot shows to the customer and to adapt them to a specific language.

POEditor project Global project (for global use cases) or local project (for local use cases) to work in.
Term Prototypical phrase of the resource to be able to locate it easily. It is composed of a reference (resource), a context and n texts (translations).
Reference (resource) It is the resource ID. Mandatory field for the subsequent importation of the term into the locales. A resource is an aura-bot element for the generation of the required text in every component of Aura response. aura-bot resources are organized in libraries of dialogs. Each resource is associated to a copy. References must not contain spaces, they should be written all together or use kebab-case in the resource name.
Translations Texts containing the translations of each language where the resource is to be used. They correspond to the texts that Aura shows to the user in a specific field of Aura response in the selected channel containing the answer to the user’s request.

Depending on the use case type, different projects and tasks must be carried out:

	Global use cases	Local use cases
POEditor project	Aura POEditor global project (Owned by Global Team)	Aura POEditor local project (Owned by LCDO Team)
Scope	- Edition of texts (copies)	- Edition of texts (copies) - Generation of resources (references)
Reference documentation	User Guide for Global Use Cases	Guidelines for the generation of resources in POEditor Guidelines for the edition of texts in POEditor

Content managers should edit texts in POEditor both for global and local use cases. Meanwhile, the generation of new resources is only required in local use cases.

Once texts or resources are modified, they are automatically imported to aura-bot during the make-up process into the settings/locale folder of the use case library.

Enter POEditor

In order to use POEditor, a license is required. Therefore, the first step is the registration of a POEditor account, if not existing, in the POEditor website.

Once registered, access your local POEditor project.

Generation of resources in POEditor

A resource is an aura-bot element needed for the generation of the required text in every component of Aura response and its subsequent importation into Aura locales.

In this particular case, for local use cases, OBs are able to generate their own resources.

Resources naming conventions

The general format for Aura resources (references in POEditor) is composed of the mandatory name of the library followed by different prefixes:

➡️[library]:[ENVIRONMENT].[CHANNEL].[SUBSCRIPTION_TYPE].[resourcename]⬅️

. Bold: mandatory fields . Italics: optional fields

[library]: mandatory field. Name of aura-bot library where the resource is contained. The library name must be the same as the name of the library that is being exported and must be configured in the locale-update script of the package.json file where the library is declared.
[ENVIRONMENT]:name of the environment. This is an optional field for the aura-bot resource that can be used in case it is required to show the user a different text in different environments. If this field is not existing, the same resource is used for every environment. The field must include the prefix of the environment (in uppercase): PRE or PRO. DEV show the same texts than PRO.
[CHANNEL]:name of the channel. This is an optional field for the aura-bot resource that can be used in case it is required to show the user a different text in different channels. This field must include the prefix of the channel (in uppercase): NOV, MH, MP,STB, STBH. If this field is not existing, the same resource is used for every channel.
[subscriptionType]: optional field. Different texts can be defined for each user’s subscriptionType, particularly: POSTPAID, PREPAID, CONTROL. They must be included in uppercase. If this field is not existing, the same resource is used for every subscription type.
[resourcename]: Name of the intended resource. It can include as many parts as needed to describe the resource. It can be expressed in a single word with lowercase (resourcename) or using kebab-case (resource-name). For example: services:services.usage.summary.

The following table shows some examples of bot resources and their associated copies in Aura:

Aura domain	Resource name (reference)	Description	Example of copy
Bundle	services:services.find.oneservices	Text associated to this resource is shown for every environment, channel and subscription type.	You´ve got %1$s contracted
Bundle	services:PRE.POSTPAID.services.usage.summary	Text associated to this resource is shown to users with subscription type postpaid in PRE environment	Let’s take a look. You’ve got %1$0.2f %2$s of data left, from your %4$0.2f %5$s allowance on %3$s, until %6$s.
Billing	bill:bill.check.genericCardText	Text associated to this resource is shown for every environment, channel and subscription type.	Let’s take a look. You’ve got one bill. It´s 2f%1$s.%2$0
Billing	bill:billing.topup.voucherincomplete	Text associated to this resource is shown for users in every environment and for every subscription type.	Top-up is not done

For each resource, there are certain pre-defined constraints (for example, the maximum number of characters) and determined variables which are common to every defined resource. The following table shows an example of these concepts.

Resource	Variables	Copy (response text)
services:services.usage.summary	%1$0.2f = Real Number, available data %2$s = Text, measuring unit for data %3$s = Text, name of bonus or plan %4$0.2f = Number, total data of bonus or plan %5$s = Text, date	Let’s take a look. You’ve got 5.5 GB of data left, from your 20 GB allowance on Custom plan, until 07-05-2019.

Precedence of prefixes

Resources are managed using a resolution matrix based on “from general to specific”. This means we will always have a generic resource in order to provide an answer to the user and, once we got it, Aura looks for a specific one if exists.

The order in the format reference is important to make the resolution matrix works properly. In this framework, the precedence of the prefixes is (from higher to lower):

SubscriptionType
Channel
Environment

The order in which the different combinations of prefixes must be checked for strings depends on the specificity (the number of matched prefixes) and the previously defined precedence order. For example, given:

library = “services”
subscriptionType = “POSTPAID”
channel = “TEST”
Environment = “PRE”
key = “title” The order of checking for matching terms must be the following (choosing the first existing translation):

services:PRE.TEST.POSTPAID.title
services:TEST.POSTPAID.title
services:PRE.POSTPAID.title
services:PRE.TEST.title
services:POSTPAID.title
services:TEST.title
services:PRE.title
services:title

Generation of a new resource in POEditor

⚠️ Remember that, for adding a new resource in the POEditor project, you need admin grants.

Follow the next steps:

Access the main page of POEditor and enter the username and password to access to the Local projects and choose the project to work on.

Select your POEditor local project and access the “Terms” option. You can see all the existing resources or search by library or name. Note that you should access “Terms” at project level (aura-bot in the example below), not for a specific language.

Click on the “Add Term” button. In this field, the new resource must be added.

Add the resource name, following the resources naming conventions.
Optionally, you can add a context in the “context” field for the categorization of the resource. It is useful for further searching purposes to include the name of the library here.

Save the resource, so it is created and added to the project.
Now, use the buttons in the right to fill in other fields:
- “Reference”: it can be added by clicking on the gear icon placed on the right hand side of the term. It should be the same as the name of the resource. It is important to fill in the “Reference”, as Aura uses it to import the resource into aura-bot.
- “Translations”: text for each different language.
- “Comments”

In order to check and modify references, please click the “R button” to the right of each term.
In order to check or edit all translations, please click the “T box”.

Resources for context filters and errors

There are special resources corresponding to errors or context filters that can be shared between libraries. The recommended way to add these resources is to duplicate them in every library that uses them.

For example, if we want a new error message to be sent when an API fails in two libraries (my-lib-1 & my-lib-2), we will add 2 resources:

my-lib-1:errors.api-error
my-lib-2:errors.api-error

In the case of context-filters, the format of the references will be, for example:

my-lib-1:context-filters.annonymous.not.allowed
my-lib-2:context-filters.annonymous.not.allowed

There is another way to add these resources:

Sharing the same resource BY adding it to a general [library] like:
- “ob-errors” (ob-errors:api-error) or
- “ob-context-filters” (context-filters:annonymous.not.allowed)
Importing it in every use case library that uses it. However, this last method has certain problems, because you need to add the new [library] to the aura-locale-importer command with the flag –b like this:
```
aura-locale-importer -u -j Aura-Bot -b my-lib-1,ob-errors -d ./settings/locale -m library -f
```
And it must be updated every time it changes in all libraries that use it to avoid conflicts during the make-up process.

Edition of texts in POEditor

At this stage, you have to edit the text (copy) of the existing resources associated with the use case under development or to translate the text to one specific language. For this purpose, follow the instructions below:

Enter your local POEditor project and then click in the desired language. All the resources and its associated texts are shown.
To find the text to be edited, there is a search box in the top-right corner of the POEditor interface. It is possible to search by key or part of a key of the resource (spanish translation of the term), or full or partial reference (key used in aura-bot for that term).
In case it is required to edit, for example, all strings concerning to account linking, search “account.linking”, which is the leading part of those strings. Each text can be edited just by clicking on the translation and modifying the text afterwards.
To find a term in a specific library, use the pattern “library_name”:

The edited texts are uploaded to aura-bot when deploying the corresponding Aura release.

Random alternative texts

aura-bot is able to show several alternative options of the same resource randomly. This behavior is provided as a platform feature and it only depends on the way the locales are defined in POEditor. The main idea is to add as many terms as alternative texts needed, keeping the same reference, as can be seen in the following picture.

When the locales are read from POEditor API to be handled by aura-bot, an array of alternatives for the given reference are stored in the locale files of the use case:

"common:common.greetings.main":[
    "Hello"
    "Hello, I am here for helping your"
],

Then, when building the response, aura-bot will return one of the options randomly.

Sorted texts

aura-bot is able to export sorted options of the same resource. If you want to guarantee the order in which the resources will be exported you have to define the resources in POEditor with numerical names(terms) starting at 0 and the same reference. For example

    core:login.loa2.cancel.keywords.0
    core:login.loa2.cancel.keywords.1

It will be exported as:

"core:login.loa2.cancel.keywords":[
    "close" (core:login.loa2.cancel.keywords.0)
    "cancel" (core:login.loa2.cancel.keywords.1)
],

This way ensure that the terms will be exported in order to the corresponding file.

Import locale files

We recommend using [aura-locale-importer() tool, a utility developed by Aura Global Team that allows locale files importation from POEditor.

Install aura-locale-importer tool:

Log in NPM to download the private NPM package dependencies. You can log in with user/password or using the token:
- User/password -> npm login
- Token -> Add the token to your environment variables on your machine. Follow the guidelines for mac/linux.
  
  ℹ️ developers should request the token for the installation of the aura-locale-importer tool from the APE Team.

Go to your use case library repository and enter the package.json file. This file contains the scripts of the project.

Go to the field locale-update and add the following command:

aura-locale-importer -u -l <language-country> -j <POEditor project> -b <my-library> -d <local-directory> -m library -f –t <token>

Where:

-l <language-country>: country translation e.g., en-gb. If this field is empty, the system imports every translation file.
-j <POEditor project>: POEditor project to be used:
. For global use cases: Aura-Bot project (global project)
. For local use cases: name of the OB’s local project
-b <my-library>: all the libraries to be uploaded by aura-bot. For example: context-filter, core, errors, suggestions, etc.
-d <local-directory>: local directory where result files are uploaded.
-f: this parameter forces the files overwriting.
-m library: it indicates the way of working. For the current release, it must be library.
-t <token>: read-only API token to access to POEditor.
- For local use cases, the local responsible of the POEditor website must, at this stage, provide you with the API token:

- Once you have the token, you can follow two different processes: - Define it in the environment variable $POEDITOR_TOKEN in the host running the process. In this case, this command should not be included here. - Add it in the current command within -t <token>

An example for a local use case in Germany is shown below:

This command generates the locale files for the “bill” library that fulfil the conditions established in the parameters above:
$ aura-locale-importer -u -l de-de -j Aura-Bot-De -b bill -d ./locale -m library -f –t f9023005c8792e57d3593511b69c300e
This command lists the content of the locale folder in the aura-bot project: $ ls .locale
The output can be one of these: de-de.json en-gb.json es-es.json pt-br.json

Once the texts and resources are imported following the process above, when a new version of the library is generated, they are automatically integrated during the make-up process.

Management of locales for intents’ canonical phrases

The management of canonical phrases for CLU intents has been implemented in POEditor, as intents must have a canonical phrase to be able to disambiguate with them.

To do this, follow the guidelines in Manage locales for canonical phrases of intents.

Hot swapping process for the update of POEditor texts

It is possible for aura-bot to load new text locale files through a hot swapping process without service outage in order to have the updated texts available in the period between one release and the consecutive one.

For this purpose, the aura-configuration-updater allows making these modifications by providing the updated locales to your local DevOps Team.

In case developers have the need of making modifications to locales belonging to aura-bridge or aura-configuration-api because of the requirements of their use cases, they can follow the process specified in the document locales-managing.

Docs:

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

HTML5

Description of HTML5 model supported by Aura

Introduction

Hypertext Markup Language revision 5 (HTML5) is markup language for the structure and presentation of World Wide Web content.

Aura Platform supports HTML5 model, therefore, it is possible to develop experiences that include HTML content in the response.

HTML5 components

There are two main components in the HTML5 model:

HTML attachments: set of models whose main property is that the content of the elements to render are composed of HTML5 tags.
HTML5 custom tags: different types of custom tags generated to send commands to Aura.

Docs:

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

Single messages response format

Description of the single message format, that allows sending a batch of messages at once

Introduction

The single message format consists on a way to send a batch of messages at once (in one single activity). Both the sender and the receiver should be capable of handling it, that is, “merging” several messages into a single one when sending, and do the reverse process when receiving.

When a channel enables singleMessage activity, it has to be prepared to process the activities sent, as they are not standard. This means doing the reverse process done in the bot, taking a single message and process every activity contained within as if they would have come one by one. Note that if the content type is application/vnd.telefonica.aura.message.single.zip, the content must be unzipped first.

Configuration

To enable single message functionality in a channel, it must be configured with singleMessage property set to true.

This property belongs to Aura channel model: ResponseOptionsVersionParameters model.

Following is an example configuration of one channel with enabled singleMessage:

[
  (...)
  {
    "responseOptions": {
      "versions": {
        "v1": {
          "singleMessage": true,
        } 
      }
    },
    "channel_id": "1234",
    "name": "example"
    (...)
  }
  (...)
]

How does single message format work?

If we want to send two simple messages, by default they will be processed as a batch, as explained in batch messages format, in order to ensure inputHint is correct.

We will, in this example, send two activities:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "text": "Primer mensaje",
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "ignoringInput"
}

and

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "text": "Segundo mensaje",
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput"
}

However, if we active the single message mode as explained before (singleMessage: true) and try to send the same two messages in a batch, we will merge them together, in a container activity, and will send only this one:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.message.single",
      "content": [
        {
          "type": "message",
          "recipient": {
            "id": "my-user",
            "name": "test-user"
          },
          "text": "Primer mensaje",
          "channelData": {
            "correlator": "5555",
            "answersCallback": "http://localhost:3000"
          },
          "inputHint": "ignoringInput"
        },
        {
          "type": "message",
          "recipient": {
            "id": "my-user",
            "name": "test-user"
          },
          "text": "Segundo mensaje",
          "channelData": {
            "correlator": "5555",
            "answersCallback": "http://localhost:3000"
          },
          "inputHint": "acceptingInput"
        }
      ],
      "name": "singleMessage"
    }
  ]
}

Note that all the activities in the batch are stored together in the content of one single attachment, with application/vnd.telefonica.aura.message.single content type and always inputHint set to acceptingInput. The channelData from the container activity (the outer-most), and therefore the correlator and dialogContext are copied from the last activity in the array (the last in the batch).

Single message mode (zipped)

If the content of a single message is big enough (specified in AURA_MAX_ATTACHMENT_JSON_SIZE env var, 10KB by default), the content will be zipped, and the content type will be application/vnd.telefonica.aura.message.single.zip.

With the previous example, we will send:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.message.single.zip",
      "content": "eJztks1y0zAQx1/F6Bw7NnY+mhNMykxT6MAhDIdODmtpHYvYkiKtHUrww3DlNfpiSEmhDMxwgOGGTpb/uz/tx//2yAg/EFuw18395yfRC0e6i2DfyciAhQjedwJspHS07zDqNb//EhmLXDqwCRsxqUxHV1IFgtwqbaXarsI/r/EalMJmJbwmpE+iRir0gkPbS45vbeOVmsi4xXj8GJGUmioLLR603SVct+MA06pH64CkVmxxZDJQr/cf3z3PD8t6up5fTd9kl1V/8XISAxtGrLK6/R4InYVY9qCeSZEt7fJ68uqw81TlX/lRDomhOyMxtPQtOxMZZLM8zp9Oq7goOI8vsCziuchFXlTzNK34I6zz7Z0+TyzT3K316nfFfkpPp/AEujOB0KJzsD1NyiDs/ng5Dwu4BILQC9fWYgOkrSdWZcZhVk5inE8mcZEXGMM8z2Mh8pSnOMtmWe4RNbgbbfHmXJFjC7IdDsPo+GutQAS8bv3gfNhteE6Rv6zPcWBMI/lpfeNeiaSV3GqnK0o4WJHUaPV5y/Qw+bIj0iqgNsOwGbEGSgx+cd3WFxI47if/Aedo6L8B/8KA/8IxFTTOW2bzFZX1doo=",
      "name": "singleMessage"
    }
  ]
}

Docs:

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

auraCommand model

Description of the auraCommand model suitable for sending intents directly to Aura with no recognition stage

Introduction

An auraCommand is an structure to send intents directly to Aura. It includes specific messages consisting on pre-defined options that the user can select from Aura’s interface as part of the response to her request. These messages come from channels using Direct Line format. Currently, they correspond to notifications and suggestions.

The aura-bot recognizer in charge of auraCommand is aura-command-recognizer-middleware. This recognizer detects if the message matches auraCommand format and then processes the message and extract the intent and entities from it.

An auraCommand should be sent within the channelData of the request to aura-bot in an optional property called auraCommand.

AuraCommand property in channelData

It is the channelData property called AuraCommand, which value should fit an AuraCommand Model.

Property	Type	Description
auraCommand	AuraCommand	This property contains an `auraCommand` object.

AuraCommand Model

Property	Type	Description
type	string	`AuraCommand` type: suggestion: used to send a common intent. The prefix of the intent must be `intent.`. Its the type by default. operation: It represents an intent that needs a context in Aura. The prefix of the intent must be `operation`. notification: It represents an intent generated by notification. The prefix must be `intent`. text: The value of the `auraCommand` contains directly a `string` with the text to be recognized by NLP. event: The value of the AuraCommand contains and event that aura-bot recognizes to carry out an action.
value	Intent model or string	Object intent or text.
utm	Utm model	Source that contains the AuraCommand.
actions	Action model	Array of actions.

Intent model

Property	Type	Description
intent	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add the it.
entities	Entity model	Array with the entities. This array can be empty.

Entity model

Property	Type	Description
type	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add it.
entity	string	Name of the entity. If this name does not contain the prefix `ent.` Aura will add it.
canon	string
score	float	Array with the entities. This array can be empty.

Utm model

Property	Type	Description
source	string	It identifies which site sent the traffic. In Aura, use the channel name.
medium	string	It identifies what type of link was used, such as cost per click or email. In Aura, use banner, button, etc.
campaign	string	It identifies a specific product, promotion or strategic campaign.
term	string	It identifies search terms.
content	string	It identifies what was specifically clicked to bring the user to the site, such as a banner ad or a text link.

Docs:

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

Batch messages response format

Description of batch messages response format

Introduction

aura-bot has two working modes for sending messages: immediate mode and batch mode, than can be selected by channel configuration.

We can configure aura-bot in immediate or batch mode by channel, in the responseOptions.versions.vX.batchMessages property, where:

vX: channelData version (v3 for channelData 3.0.0).

Configuring it this way, we are able to send batch messages only in certain channels.

Immediate mode

In immediate mode, when a message is sent by a dialog or middleware, it is sent directly to the user (after executing the outgoing middlewares), without delays.

Batch mode

In batch mode, aura-bot intercepts and stores all the sending messages (after being processed by the outgoing middlewares), and sends them all at once on turn end.

When using batch mode and all the messages are gathered from the bot message queue and processed together to assure that the inputHint is correct in all of them, then the behavior is as follows: All but the last message is set to ignoringInput, as the specification says, and the last message maintains the status set by the dialog or, if it has not been defined (undefined), is set to acceptingInput. Note that if a dialog sends a prompt, it is its responsibility to send the proper inputHint, in this case expectingInput.

The activities array may contain messages for multiple channels, we can use the method filterByConversationId that returns activities classified by conversationId. This classification allows setting the inputHint correctly for each channel.

The legacy hasMoreMessages flag in channelData is also set when batch processing the messages, but this flag will disappear in near future.

Docs:

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

Guidelines for the design of cards in Aura response

Discover how to design different types of Microsoft cards and include them in the response that Aura provides to its users

Introduction

A card is a visual element that brings context to the answer in Aura response. It can contain images, graphic resources, texts and buttons and, through these elements, acts as a useful tool to summarize the information and present it in a structured and friendly-user way.

The design of the card in Aura response can be done through different tools, depending on the specific channel and its rendering capabilities. Two types of cards can be rendered by the most common Aura channels:

Microsoft Adaptive Cards: tool that provides developers an open card exchange format for the design of a customizable card content in a consistent way.
Hero Cards: they typically contain a single large image, one or more buttons and text, providing a flexible layout.
Moreover, there are other different data exchange formats in Aura such as custom JSON model, JSON response model or ZIP response model.

The procedure for declaring Adaptive Cards and Hero cards in a use case’s dialog is fully explained in the following sections.

There is a set of new utilities that you can use when working with these two types of Cards, included in the Microsoft Documentation: CardFactory class.

Microsoft Adaptive Cards

Microsoft Adaptive Cards is a tool that provides developers an open card exchange format for the design of a customizable card content in a consistent way.

For the generation of an Adaptive Card and its inclusion into aura-bot when developing a use case, developers should follow the steps shown below:

Design the Adaptive Card through the Adaptive Cards designer, that includes a simple drag and drop interface as shown in the following figure.
ℹ️ Developers in charge of building Aura response are kindly requested to read the Adaptive Cards documentation in order to understand how to design a card.
Once the card is designed, automatically, the design parameters and texts are loaded in a JSON file.

Copy the generated JSON file in the Adaptive Card designer and paste it in the source code of the use case dialog. It is recommended to copy it in [dialog-name]-util.ts for a proper readability of the dialog files. An example is shown below, where:
- contentType: this field must be filled in with the following value: 'application/vnd.microsoft.card.adaptive'
- content: the JSON object generated in Microsoft Adaptive Cards card payload editor must be included in this field.

export function getIssueCreationConfirmationAdaptiveCard(stepContext: WaterfallStepContext, localizer: LocaleManager,
    description: string, configuration: Configuration) {
    const correlator = ContextUtils.getCorrelator(stepContext.context);
    const auraUser: AuraUserBaseModel<any> = ContextUtils.getAuraUser(stepContext.context);
    const issueCreationConfirmationAdaptiveCard = {
        contentType: 'application/vnd.microsoft.card.adaptive',
        content: {
            type: 'AdaptiveCard',
            version: '1.0',
            body: [{
                type: 'ColumnSet',
                columns: [{
                    type: 'Column',
                    width: 'auto',
                    items: [{
                        type: 'Image',

                        url: DialogUtils.getResourcePath('issues', 'images/icn_assistant_issue.png', configuration)
                    }]
                }, {
                    type: 'Column',
                    items: [
                        {
                            type: 'TextBlock',
                            text: localizer.getText('issues:issues.common.issue', auraUser, correlator),
                            size: 'medium',
                            weight: 'bolder',
                            horizontalAlignment: 'left'
                        }
                    ]
                }
                ]
            }, {
                type: 'ColumnSet',
                separator: true,
                spacing: 'medium',
                columns: [{
                    type: 'Column',
                    items: [{
                        type: 'TextBlock',
                        text: description,
                        size: 'small',
                        wrap: true,
                        maxLines: 5,
                        horizontalAlignment: 'left'
                    }]
                }]
            }] as any[]
        }
    };
    return issueCreationConfirmationAdaptiveCard;
}

If specific graphic resources are included in the card:

4.1. Follow the procedure defined for the generation of graphic resources in Aura response for static resources or dynamic ones.

4.2. Declare the resource in the URL field of the card JSON file.

url: DialogUtils.getResourcePath('library_name', 'image_name',  configuration)

In the previous example:

`url: DialogUtils.getResourcePath('issues', 'images/icn_assistant_issue.png', configuration)`

4.3. In order to get a complete URL, including device screen resolution, invoke getImageUrl from the library aura-bot-library-utils if the image has got several resolutions (instead of getResourcePath).

Microsoft Hero Cards

Hero Cards typically contain a single large image, one or more buttons and text, providing a flexible layout.

For the generation of a Hero Card and its inclusion into aura-bot when developing a use case, follow the steps below:

Design the Hero Card. For this purpose, developers are kindly requested to read the Hero Cards documentation for acquiring the required knowledge regarding this type of cards.

Declare the Hero card in the use case dialog. For efficiency purposes, it is recommended to include them in the [dialog-name]-util.ts.

An example of the source code for including the Hero Card in the dialog is shown below. The last line indicates how the Hero Card is sent to the bot.

const cardActions: any[] = [
     {type: ActionTypes.OpenUrl, title: 'Button 1 title', value: 'www.google.es'},
     {type: 'openUrl', title: 'Button 2 title', value:  'www.google.es'}];
const card: Attachment = CardFactory.heroCard('', undefined, cardActions);
const reply: Partial<Activity> = {
   type: ActivityTypes.Message,
   attachments: [card]
};
await stepContext.context.sendActivity(reply);

If specific graphic resources are included in the card:

3.1. Follow the procedure defined for the generation of graphic resources in Aura response for static resources.
3.2. Declare the resource in the card as an attachment.
CardFactory.heroCard('', undefined, cardActions);
Where:
- ‘’: Hero Card text
- undefined: Images in the Hero Card
- cardActions: Actions
If, for example, the image icon.png is to be included in the Hero Card, then the field “undefined” must be replaced by heroCardImages:
```
const card: Attachment = CardFactory.heroCard('', heroCardImages, cardActions);
const heroCardImages: string[] | CardImage[] = [DialogUtils.getResourcePath('issues', 'images/icon.png', configuration)]
```
3.3. In order to get a complete URL, including device screen resolution, invoke getImageUrl from the library aura-bot-library-utils if the image has got several resolutions (instead of getResourcePath).

Docs:

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

HTML5 custom tags

Custom tags generated to send commands to Aura

Introduction

Discover the different types of custom tags supported by Aura.

Find here general information regarding custom elements.

Aura action tags

The function of this set of tags is to encapsulate all the interactions within the HTML that is sent in the attachment. Any iteration that occurs within the HTML code must generate an event. In this way, the channel only has to manage the events that occur from these tags.

Capabilities:

Action tags define the type of event triggered:
- External as auracommand
- Internal as internal channel capability
- etc.
Action tags define the trigger to activate the action by voice.
Action tags define the targets of HTML elements that is associated to this action by an event.

Aura action: <aura-action>

This tag contains a collection of sub-tags in which the targets, triggers and events necessary to perform this action will be determined.

Property	Description
id	Optional identifier
name	Custom name of the action

Example:

<aura-action name="selectSeat">

</aura-action>

Aura action trigger: <aura-action-trigger> (Not implemented yet)

This tag is used to identify an action based on a voice message from the user.

Initially, are only two types:

Regex
Proximity

The recognition of the intention of this voice message may be associated with entities.

Property	Description
id	Optional identifier.
type	Recognizer type: `Regex`: A regular expression engine is executed to determine if the value of reg expression matches with the message of voice. This expression may contain groups to identify entities. `Proximity`: This type uses a proximity phrase comparison algorithm. Based on a minimum resemblance value (min-threshold), it will determine if the event will be triggered. You can include entities in the `entity` field.
value	Text to compare. If the type is `Regex`, this text must be a regular expression.
entity	It represents one o more entities to send to the event if the trigger is activated.
entity-field	In the case of a regular expression, it represents an entity calculated on the basis of the regular expression.

Examples:

    <aura-action-trigger type="regex" value="/select seat ([1-500])/" entity-field="$1">  </aura-action-trigger>
    <aura-action-trigger type="proximity" min-threshold="0.99" value="select seat 1C" entity="32">  </aura-action-trigger>

Aura action target: <aura-action-target>

It defines the targets of HTML elements that are associated to this action by an HTML event.

Property	Description
id	Optional identifier.
target	Pattern to determine the identifiers of the tags from the elements that compose the HTML. The format of the pattern is a querySelector syntax.
event	HTML event to which the action should be associated. For example: `click`
evalue	JSON Object to validate. The JSON object has the properties `field` and `value`. The evaluation returns `true` if the field contains the value. Example: `{"field":"checked", "value":true}`
mode	Modality of target element: `submit`, `single` or `multiple`. submit: this value indicates that the composition of the aura-event will be done after the event is launched. single: this value indicates that you only need to evaluate one element independently. multiple: this value indicates that the final composition depends on a set of elements.
entity-field	It represents a property in the target element to be used as entity.
voice-field	It represents a property in the target element to be used for dialogContext models. This value can contain multiple string fields separated by pipes (`\`, `
canon-field	It represents a property in the target element to be used as canon.
entity-type	It represents the type property of the entity model
entity-default	Used to set a entity by default when the command is build.
canon-default	Used to set a canon by default when the command is built.
voice-default	Used as an alternative for voice-field.

Aura action event: <aura-action-event>

It contains the event that will be generated if the action is activated. This event is associated with a data model that contains the information related to the event.

Property	Description
id	Optional identifier. Optional
type	Type of event generated if the action is launched. Values: `auraCommand`.
intent	Intent of the command.
command-type	Type of auraCommand. Values: `intent`, `operation` or `text`.
event-hook	Event to hook the result of the event. It is used to add an event listener to capture the event and result of an aura-action-event. Example: `aura-la-event`. Example of capture: `document.body.addEventListener("aura-la-event", customFunction, true)`.

Examples

To capture the events:

<script>
  /** To capture the event
  /* 1.- Add the listener
  **/
  document.body.addEventListener("seatSelected", customFunction, true);
  /* 2.- create the function to execute */
  function customFunction(e) {
    console.log(e.detail);
}
</script>

Single Button

<input type="button" id="b-1" data-seat="1A" value="Seat 1A" />
<input type="button" id="b-2" data-seat="1B" value="Seat 1B" />
<input type="button" id="b-3" data-seat="1C" value="Seat 1C" />
<input type="button" id="b-4" data-seat="1E" value="Seat 1E" />
<input type="button" id="b-5" data-seat="1F" value="Seat 1F" />
<!--Aura custom tags-->
<aura-action id="selectSingleButton">
   <aura-action-target target="[id^=b-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if button with id=b-1 was clicked:

{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                }
            ]
        }
    }
}

Multiple button

<input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" /> <br /> <br />
<input type="button" id="sbm" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleButton">
   <aura-action-target target="[id^=bm-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=sbm]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Radio Button

<input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="srbseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectSimpleRadio">
   <aura-action-target target="[name^=rbseat]"  entity-field="value" canon-field="data-seat" entity-type="seat" mode='single'  evalue='{"field":"checked", "value":true}'> </aura-action-target>
   <aura-action-target target="[id^=srbseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Checkbox Button

<input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="checkbox" name="chkseat"  data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="schkseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectByCheckboxMultiple">
   <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=schkseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if the first and the last checkboxes were checked:


{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                },
                {
                    "entity": "1E",
                    "type": "seat",
                    "canon": "Seat 1E"
                }
            ]
        }
    }
}

Select Single

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
<!--Aura tags-->
<aura-action id="selectSingleOption">
   <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='single' > </aura-action-target>
   <aura-action-target target="[name^=selectOpt]" event="change" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Select Multiple

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
 <input type="button" id="smop" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleOption">
   <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='multiple' > </aura-action-target>
   <aura-action-target target="[id^=smop]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Input Text

<input type="text" id="textSelect" />
<input type="button" id="textType" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectText">
   <aura-action-target target="[id^=textSelect]" entity-field="value" canon-field="value" evalue="" entity-type="seat" mode='single'> </aura-action-target>
   <aura-action-target target="[id^=textType]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

All In One

<body>
   <section>
      <input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" />     
   </section>
   <section>
      <input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br />
   </section>
   <section>
      <input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="checkbox" name="chkseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> 
   </section>
   <section>
      <select name="selectOpt">
         <option value=""></option>
         <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
   </section>
   <section>
      <select name="mselectOpt" multiple>
         <option id="mop-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="mop-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="mop-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="mop-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="mop-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
      <br />
   </section>
   <section>
      <input type="text" id="textSelect" /> 
      <input type="button" id="textType" data-seat="send" value="Submit" />
   </section>
   <!--Aura tags-->
   <aura-action id="selectSeat">
      <aura-action-target target="[id^=bm-]" event="click" entity-field="data-seat" canon-field="value" entity-type="seat2" mode='multiple'> </aura-action-target>
      <aura-action-target target="[name^=rbseat]" entity-field="value" canon-field="data-seat" entity-type="seat3" mode='single' evalue='{"field":"checked", "value":true}'> </aura-action-target>
      <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat4" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat5" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat6" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=textSelect]" entity-field="value" evalue="" canon-field="value" entity-type="seat7" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=textType]" event="click"  mode='submit'> </aura-action-target>
      <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
   </aura-action>
</body>

Docs:

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

Build Aura response

When developing a use case, a crucial step is to design the response that Aura provides to its users.

Learn how to generate it using the most appropriate texts and elements.

Introduction

Aura must be able to deal with messages from different partners in several languages and, moreover, from different communication channels.

Considering a user request to Aura through a specific communication channel, Aura must provide the appropriate answer to his/her utterance through a precise message expressed in the user’s language and in natural language.

The response to the user can be provided through three different interfaces, depending on the communication channel:

Custom interface: Interface with screen, voice and text interaction. This is the main Aura interface.
Voice interface: Interface for devices without screen, where the interaction is only done through voice.
Chat interface: Message interface where the text is the main interaction mode, based on a conversational model with bubbles and historic data.

Depending on the channel and its rendering capabilities, the response can include different elements: text, cards, graphic resources, deeplinks, suggestions and actions.

The following documents include the guidelines for the generation of three key elements in Aura response:

Texts: how to generate or update Aura response texts in POEditor.
Cards: different types of cards that can be included in Aura response as visual elements.
Graphic resources: static or dynamic graphic resources that can be included in the response to the user.

Docs:

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

Guidelines for the design of graphic resources in Aura response

Learn how to design of different types of graphic resources and include them in the response that Aura provides to its users

Introduction

You can design your own graphic resources inside the visual components of Aura response (mainly, in the card), always depending on the rendering capability of the channel.

They are categorized into two main groups:

Static graphic resources: icons, images, diagrams, etc.
Dynamic graphic resources: graphics that include users’ data and change depending on them (for instance, new plot for data usage use case per country). These graphics can fetch data from Kernel or from external services (for instance, images from smartphone models that can be shown to the user).

The following sections define the procedure for including both a static and dynamic graphic resource in Aura response.

Include static resources by library

The static resource must be previously defined in the resources/ folder of the use case library.
In the use case dialog (.ts file), each resource must be declared as shown in the following snippet:
```
import * as libraryUtil from '@telefonica/aura-bot-utilities/lib/aura-bot-library-util';
(...)
const wholeUrl = libraryUtil.getResourcePath(config, 'my_library', 'icon.png');
```
Where:
- config: configuration object that should contain the environment variables AURA_STATIC_RESOURCE_ENDPOINT and AURA_STATIC_RESOURCE_SAS_TOKEN.
- 'my_library': library name
- 'icon.png': name of the image
In order to get a complete URL, including device screen resolution, invoke getImageUrl from the library aura-bot-library-utils.
In the index.ts file of your use case library, the resources path must be exposed in the resources property when registering the plugin, as shown in the following example:
```
register(null, {
    my_library: {
       …
        resources: path.resolve(__dirname, '..', 'resources'),
        (...)
    }
```
Where:
- 'resources': name of the folder where the resources are defined, within the library.
Just after it, the resource must be uploaded to Microsoft Azure Storage Explorer, in the images/ folder of the corresponding library. Doing so, Azure generates an URL for the defined resource.

Hot swapping of static resources

Once a static resource is created through the above defined steps, the OB can follow a hot swapping process for the modification of the resource:

The name of the icon must not be modified: it has to be the same as the name in the code.
Updata de resource file directly in Microsoft Azure Storage Explorer, in the /resources/images/ folder of the corresponding library. Doing so, Azure generates an URL for the defined resource.
However, it must be taken into account that, during the make-up process, the bot overwrites it, so the updating process should be repeated by the OB. For example, this process can be executed when publishing a local use case.
It is not necessary to restart the bot, as the method which is invoked internally already fetches the icon from Azure Storage.

Include a dynamic graphic resource

The inclusion of dynamic graphic resources in Aura involves two main stages:

Data recovery from a Kernel API or from an external API For Kernel APIs, follow the process in the document Create / update an API client.
Generation of dynamic graphic resources: Developers must implement their own dynamic graphic resources generator. After generating the resource, the process of uploading the resource into Azure must be done manually.
If the dynamic resource is integrated into the card of Aura response, follow the instructions in Build Aura response: cards.

Docs:

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

dialogContext model

Description of the dialogContext model, for the management of different existing options in the response

Introduction

A dialogContext is a structure that facilitates the recognition of CardActions and prompts without the need of training.

It has the following characteristics:

It can be autogenerated when a prompt is active.
It can be autogenerated when there is a CardAction.
It can be created manually in a dialog but with certain restrictions.
It is stored in the conversation cache.
It is processed by the dialog-context-recognizer-middleware.
It is auto-generated and stored by the aura-bot adapter.
It can be configured at channel level, prompt level and CardAction level.
It facilitates the recognition of CardActions if a user, instead of pressing the button, types the button text.
It facilitates the recognition of numbered lists either by ordinals or cardinals.
It uses a proximity search algorithm.
It solves the problems of the recognition of numbers and ordinals that the current Bot Framework prompt has.

Existing models

dialogContext model

Property	Type	Description
text	String	Text or texts (separated by ‘\|’) with the options to be matched.
value	Object	Object of `IntentResult` or other with the action to carry out if the option is validated.

Example:

"dialogContext": [
                    {
                        "text": "Hello",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "greetings",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    },
                    {
                        "text": "Bye bye mi picolissima dama",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "goodbyes",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    }
                ]

Channel model

The dialogContext model at the channel level applies to all dialog components.

This model has the highest priority, i.e., in case of conflict between models, the channel model has the highest weight.

This model is inside the responseOptions.dialogContext property. Check it in Aura channel model: ResponseOptions model.

An example is shown below:


channel: {
...
        responseOptions: {
            dialogContext: {
                normalizeTerms: true,
                disabled: false,
                disabledMerge: false,
                processFromClient: false,
                returnToClient: false,
                defaultListType: 'none',
                promptChoice: {
                    generate: 'never',
                    generateList: false
                },
                cardActions: {
                    generate: 'never',
                    generateList: false
                }
            }
        }
    },
...

Prompt model

The options of dialogContext for a prompt can be included inside the property validations of Prompt Options within its sub-property dialogContext.

When generating the list of options, the system takes into account two properties of the prompt: recognizeNumbers and recognizeOrdinals.

In these cases:

If the prompt has recognizeNumbers=false and we have activated the list of options, only the ordinal values of each option will be generated.
If the option recognizeOrdinals=false, then only the cardinal options will be generated.
If both are set to false, no list items will be generated.

By default, the prompt has both properties set to true.

Property	Type	Description
originalFindChoicesOptions	Object	Original prompt findChoiceOptions. Used if the dialogContext recognizer needs to change it, the prompt would be restored to the original state.
originalStored	Boolean	It indicates whether the dialogContext recognizer had to overwrite the original prompt values. Default: `false`.
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for prompt options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of list to enumerate the prompt options. Default: `OrdinalCardinal`.

Example of prompt options:


{
  "Choices": [
    {
      "value": "Lunes",
      "synonyms": [
        "El lunes"
      ]
    },
    {
      "value": "martes"
    }
  ],
  "validations": {
    "dialogContext": {
      "enabled": true,
      "listType": "ordinal "
    }
  }
}

CardAction model

The options of dialogContext for a CardAction can be included inside the property channelData of button options, within the sub-property dialogContext.

Property	Type	Description
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for CardAction options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of the list to enumerate the CardAction buttons. Default: `OrdinalCardinal`.
synonyms	String[]	Array of strings with synonyms of the title.

{
  "buttons": [
    {
      "type": "postBack",
      "title": "Monday",
      "value": {
        "intent": "monday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal"
        }
      }
    },
    {
      "type": "postBack",
      "title": "Wednesday",
      "value": {
        "intent": "wednesday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal",
          "synonyms": [
            "X"
          ]
        }
      }
    }
  ]
}

Custom dialogContext

It is possible to add in the channelData a dialogContext manually. If the channel configuration allows it, this will be merged with the _dialogContext that is generated automatically.

The following rules must be taken into account when including our own dialogContext:

Do not generate the list values, that is, do not add ordinals and/or cardinals, as this will be done by the system.
The options of a custom dialogContext are included right at the top of the list.

How does dialogContext work?

The dialogContext flowchart includes two differentiate phases: recognition phase and build phase, described below.

Recognition phase

When validating if the user has entered a phrase that matches the dialogContext that we have generated from the previous answer, take into account that the comparison is done by proximity.

The match value will be reported in a score field that goes from 0 to 1. Valid values will be those that are greater or equal to a given threshold. For a dialogContext we have two thresholds.

AURA_DIALOG_CONTEXT_THRESHOLD: Default threshold when comparing two strings. Default value: 0.80.
AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD: Threshold used in case dialogContext elements are in list form and also if the input phrase includes a number. By default, 0.95.
This value is so high because if the user writes ‘11’ or ’the 11’, and there are only 5 elements in the list, the comparison could give us a very high value, since comparing 11 with 1 has a threshold higher than 0.80, which means that writing 11 would select the first option. To avoid this kind of cases when there are numbers in the user input and the list is enumerated, then the threshold should be stricter.

Another thing to take into account is that if the dialogContext does not get a valid match, if we have an active prompt choice, the system will override its recognizeNumbers and recognizeOrdinals properties, as long as we are working with enumerated elements.

This is done because when MS Bot Framework detects an ordinal number in a sentence, it ignores the rest of the sentence, which can lead to many errors. These values are restored every time the prompt is regenerated if it has not been resolved.

In the recognition phase, the dialogContext recognizer compares value to value, and in the case that one of them meets the conditions, the intention associated with the value is established. It also assigns to the input text the value expected by the prompt, in case there is one.

Example:

DialogContext

[
  {
    "text": "1|the 1|one|the one|first|the first|Monday",
    "value": {
      "intent": "monday"
    }
  },
  {
    "text": "2|the 2|two|the two|second|the second|Tuesday",
    "value": {
      "intent": "tuesday"
    }
  },
  {
    "text": "3|the 3|three|the three|third|the third|X|Wednesday",
    "value": {
      "intent": "wednesday"
    }
  },
  {
    "text": "4|the 4|four|the four|fourth|the fourth|Thursday",
    "value": "The Thursday"
  },
  {
    "text": "5|the 5|five|the five|fifth|the fifth|Friday",
    "value": "Friday"
  }
]

User Input: the 4

In this case, as the list is numbered and the user has entered a number in his sentence, the selected threshold will be AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD.
The elements of each option will be compared with the user’s value:

   1 ≅ the 4  -> Score 0 
   the 1 ≅ the 4  -> Score 0.80
   ......
   the 4 ≅ the 4  -> Score 1.0   -> Option Selected

If the selected option has value, the value is assigned to the activity text. In other case, the assigned value is the last value of the text, in this case ‘Thursday’.
If there is a prompt choice, the validations recognizeNumbers and recognizeOrdinals are set to false.

Build phase

The build phase is responsible for collecting the customized dialogContext (if any) and, in turn, for generating the dialogContext of the CardActions and Prompt in the different activities that make up the output message.

The enumeration of the elements depends on the configuration of the channel and the respective components. Once generated, it is stored in the user’s conversation cache.

The module in charge of this procedure is the Aura Bot Adapter.

Docs:

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

Files message response format

Description of the capability of Aura use cases to exchange files with the customers

Introduction

Aura integrates the capability of managing files in certain channels. Currently, WhatsApp channels.

This feature is available in a bidirectional way:

A WhatsApp use case can send a file to the user
A user can send a file to a WhatsApp use case

Access the documentation in Use of files in WhatsApp.

Docs:

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

Audiovisual App Opening use case resources

Resources used by the Audiovisual App Opening use case

Introduction

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

Specific resources for the use case

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

Specific resources for intent.tv.app_open use case	Definition	Example	Managed by	Scope

`tv:video.section.not_available`	Resource returned when the section is not available		tv.app_open plugin	Use case-specific

Docs:

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

Change language use case resources

Resources used by the Change language use case

Introduction

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

Docs:

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

Section Show use case resources

Resources used by the Section Show use case

Introduction

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

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:

Specific resources for tv.display use case	Definition	Example	Managed by	Scope
`navigation:navigation.section_show`	Resource returned when the navigation section show is successfully		navigation.section_show plugin	Use case-specific

Docs:

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

Subtitles remove use case resources

Resources used by the Subtitles remove use case

Introduction

The Subtitles remove use case will use three different types of resources:

Docs:

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

Template messages response format

Description of the capability of Aura use cases to send templates to the customers

Introduction

Aura integrates the capability of including templates in a use case for the enrichment of the response provided to the users through the combination of different elements (multimedia, buttons, different designs for texts, etc.).

Currently, this feature is available in WhatsApp channels and unidirectionally: from WhatsApp to the user.

Access the documentation in Use of templates in WhatsApp.

Docs:

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

TV content get info use case resources

Resources used by the TV content get info use case

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

Specific resources for the use case: tv.content_get_info

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

Specific resources for tv.content_get_info use case	Definition	Example	Managed by	Scope
`tv:video.content-get-info.by-channel.no-results`	Resource returned when the search does not find any result with channel info	Lo siento, no encuentro lo que dices	tv.content_get_info plugin	Use case-specific
`tv:video.content-get-info.by-channel.single-result`	Resource returned when the search finds one channel	Esto es lo que están emitiendo ahora en ese canal	tv.content_get_info plugin	Use case-specific
`tv:video.content-get-info.by-channel.multiple-results`	Resource returned when the search finds more than one channel	He encontrado estos contenidos que se estan emitiendo	tv.content_get_info plugin	Use case-specific

Docs:

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

TV LLM Conversational Search UC resources

Resources used by the TV LLM Conversational Search UC

Introduction

The TV LLM Conversational Search UC will use three different types of resources:

Specific resources for the use case: TV LLM Conversational Search

In case the LLM Conversational Search does not return the text to be shown to the user, the resources from TV Conversational Search plugin would be used

The resources associated to aura-bot are defined below:

Specific resources for TV LLM Conversational Search use case	Definition	Example	Managed by	Scope
`tv-conversational-search:command.exit`	Resource returned when the user sends a message to stop the dialog and launch a different UC	Entendido. Recuerda que puedes volver a probarlo diciendo “Recomendador avanzado"	conversational-search dialog	Use case-specific
`tv-conversational-search:command.close.words`	Resource returned when the user sends a message to stop the dialog. By default, it is not configured.	Salir, cerrar, goodbye, exit, quit	conversational-search dialog dialog	Use case-specific
`tv-conversational-search:command.no-results`	Resource returned in case there is no results	Ahora mismo no encuentro resultados, pero si me dices un género o tu estado de ánimo te sugiero algo.	conversational-search dialog	Use case-specific
`tv-conversational-search:command.recommend`	Resource used to call the LLM with a fixed phrase when the request comes from triage	Recomendación avanzada	conversational-search dialog	Use case-specific

The resources associated to the TV LLM Conversational Search plugin are defined below:

Specific resources for TV LLM Conversational Search use case	Definition	Example	Managed by	Scope
`tv:video.conversational.by-default.simple-result`	Resource returned when finds one result as recommendation	Here is a suggestion	tv.recommend plugin	Use case-specific
`tv:video.conversational.multiple-results`	Resource returned when finds more than one result as recommendation	Here are some suggestions	tv.recommend plugin	Use case-specific
`tv:video.conversational.display.single-result`	Resource returned when one live channel is recommended and starts playback	Tuning to channel	tv.recommend plugin	Use case-specific
`tv:video.conversational.no-results`	Resource returned when does not find any result as recommendation	Nothing found	tv.recommend plugin	Use case-specific

Docs:

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

TV Custom Recommendation use case resources

Resources used by the TV Custom Recommendation use case

Introduction

The TV Custom Recommendation use case will use three different types of resources:

Specific resources for the use case: tv.custom_recommendation

The resources associated to the TV Custom Recommendation plugin are defined below:

Specific resources for tv.custom-recommendation use case	Definition	Example	Managed by	Scope
`tv-custom-recommendation:command.exit`	Resource returned when the user sends a message to stop the dialog and launch a different UC	Entendido. Recuerda que puedes volver a probarlo diciendo “Recomendador avanzado"	tv.custom_recommendation dialog	Use case-specific
`tv-custom-recommendation:command.close.words`	Resource returned when the user sends a message to stop the dialog. By default, it is not configured.	Salir, cerrar, goodbye, exit, quit	tv.custom_recommendation dialog	Use case-specific
`tv-custom-recommendation:error.message`	Resource returned in the happening of an error	Algo no ha ido bien, inténtalo de nuevo	tv.custom_recommendation dialog	Use case-specific
`tv-custom-recommendation:command.none`	Resource returned when ATRIA does not recognize what the user is saying and returns a topic of “[None]”	Uy, no tengo claro a qué te refieres	tv.custom_recommendation dialog	Use case-specific
`tv-custom-recommendation:command.unknown-error`	Resource returned when ATRIA returns a tagged topic that is not matched in the dialog.	Algo no ha ido bien, inténtalo de nuevo	tv.custom_recommendation dialog	Use case-specific

Docs:

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

TV display use case resources

Resources used by the TV display use case

Introduction

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

Specific resources for the use case: tv.display

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

Specific resources for tv.display use case	Definition	Example	Managed by	Scope
`video.display.by-channel.single-result`	Resource returned when the search finds one channel and is broadcasting	Esto es lo que están emitiendo ahora en ese canal	tv.display plugin	Use case-specific
`video.display.by-default.single-result`	Resource returned when the search finds one channel content has already been broadcast or finds a video content	Voy a ello, dame un segundo	tv.display plugin	Use case-specific
`video.display.by-default.detail-result`	Resource returned when the search finds one channel content or video content that has not been broadcast yet, or the content does not have enough information to be played	Mira, he encontrado este contenido	tv.display plugin	Use case-specific
`tv:video.display.by-default.multiple-results`	Resource returned when the search finds more than one channel content or content on demand	He encontrado estos contenidos relacionados con tu petición	tv.display plugin	Use case-specific
`tv:video.display.contingency.single-result`	Resource returned when the contingency search finds one result	He encontrado este contenido relacionado	tv.display plugin	Use case-specific
`tv:video.display.contingency.multiple-results`	Resource returned when the contingency search finds more than one result	He encontrado estos contenidos relacionados	tv.display plugin	Use case-specific
`tv:video.display.contingency.no-results`	Resource returned when the contingency search does not find any result	Lo siento, no encuentro lo que dices	tv.display plugin	Use case-specific

Docs:

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

Resources used by the TV LLM Recommend UC

Introduction

The TV LLM Recommend UC will use three different types of resources:

The resources associated to the TV LLM Recommend plugin are defined below:

Specific resources for TV LLM Search use case	Definition	Example	Managed by	Scope
`tv:video.recommend.by-default.simple-result`	Resource returned when finds one result as recommendation	Here is a suggestion	tv.recommend plugin	Use case-specific
`tv:video.recommend.multiple-results`	Resource returned when finds more than one result as recommendation	Here are some suggestions	tv.recommend plugin	Use case-specific
`tv:video.recommend.display.single-result`	Resource returned when one live channel is recommended and starts playback	Tuning to channel	tv.recommend plugin	Use case-specific
`tv:video.recommend.no-results`	Resource returned when does not find any result as recommendation	Nothing found	tv.recommend plugin	Use case-specific

Docs:

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

TV LLM Search UC resources

Resources used by the TV LLM Search UC

Introduction

The TV LLM Search UC will use three different types of resources:

Specific resources for the use case: TV LLM Search

The resources associated to the TV LLM Search plugin are defined below:

Specific resources for TV LLM Search use case	Definition	Example	Managed by	Scope
`tv:video.retrieve.by-default.simple-result`	Resource returned when the search finds one result	Here is the content I found	tv.retrieve plugin	Use case-specific
`tv:video.retrieve.multiple-results`	Resource returned when the search finds more than one result	Here are the contents I found	tv.retrieve plugin	Use case-specific
`tv:video.retrieve.display.single-result`	Resource returned when the search finds a single live channel and starts playback	Tuning to channel with live channel	tv.retrieve plugin	Use case-specific
`tv:video.retrieve.no-results`	Resource returned when the search does not find any result	I haven’t found anything	tv.retrieve plugin	Use case-specific

Docs:

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

TV move backwards use case resources

Resources used by the TV move backwards use case

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

Docs:

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

TV move forwards use case resources

Resources used by the TV move forwards use case

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

Docs:

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

TV none use case resources

Resources used by the TV none use case

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

Specific resources for the use case: tv.none

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

Specific resources for tv.none use case	Definition	Example	Managed by	Scope
`tv:video.search.contingency.no-results`	Resource returned when the contingency search does not find any result	No he encontrado nada	tv.none plugin	Use case-specific
`tv:video.search.contingency.single-result`	Resource returned when the contingency search finds one result	Este es el resultado que he encontrado	tv.none plugin	Use case-specific
`tv:video.search.contingency.multiple-results`	Resource returned when the contingency search finds more than one result	Estos son los resultados que he encontrado	tv.none plugin	Use case-specific

Docs:

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

TV search use case resources

Resources used by the TV search use case

Introduction

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

Specific resources for the use case: tv.search

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

Specific resources for tv.search use case	Definition	Example	Managed by	Scope
`tv:video.search.by-title.simple-result`	Resource returned when the search finds one result by searching for one title entity	He encontrado esto sobre $title	tv.search plugin	Use case-specific
`tv:video.search.by-title.multiple-results`	Resource returned when the search finds more than one result by searching for one title entity	He encontrado estos contenidos sobre $title	tv.search plugin	Use case-specific
`tv:video.search.by-participant.simple-result`	Resource returned when the search finds one result by searching for one actor/director entity	En este contenido participa $participant	tv.search plugin	Use case-specific
`tv:video.search.by-participant.multiple-results`	Resource returned when the search finds more than one result by searching for one actor/director entity	En estos contenidos participa $participant	tv.search plugin	Use case-specific
`tv:video.search.by-genre.simple-result`	Resource returned when the search finds one result by searching for one genre entity	Mira lo que he encontrado sobre $genre	tv.search plugin	Use case-specific
`tv:video.search.by-genre.multiple-results`	Resource returned when the search finds more than one result by searching for one genre entity	Estos son los contenidos que he encontrado sobre $genre	tv.search plugin	Use case-specific
`tv:video.search.by-subgenre.simple-result`	Resource returned when the search finds one result by searching for one genre and one subgenre entity	Mira lo que he encontrado sobre $genre de $subgenre	tv.search plugin	Use case-specific
`tv:video.search.by-subgenre.multiple-results`	Resource returned when the search finds more than one result by searching for one genre and one subgenre entity	Estos son los contenidos que he encontrado sobre $genre de $subgenre	tv.search plugin	Use case-specific
`tv:video.search.by-default.simple-result`	Resource returned when the search finds one result	Aquí tienes este contenido	tv.search plugin	Use case-specific
`tv:video.search.by-default.multiple-results`	Resource returned when the search finds more than one result	Aquí tienes estos contenidos	tv.search plugin	Use case-specific
`tv:video.search.contingency.no-results`	Resource returned when the contingency search does not find any result	No he encontrado nada	tv.search plugin	Use case-specific
`tv:video.search.contingency.single-result`	Resource returned when the contingency search finds one result	Este es el resultado que he encontrado	tv.search plugin	Use case-specific
`tv:video.search.contingency.multiple-results`	Resource returned when the contingency search finds more than one result	Estos son los resultados que he encontrado	tv.search plugin	Use case-specific
`tv:video.search.no-results`	Resource when the contingency search is disabled and does not find any result	No he encontrado lo que dices	tv.search plugin	Use case-specific

Docs:

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

TV VOD EPG information use case resources

Resources used by the TV VOD EPG information use case

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

Specific resources for the use case: tv.vod_epg_information

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

Specific resources for tv.vod_epg_information use case	Definition	Example	Managed by	Scope
`tv:tv.moreInfoTvDetail`	Resource returned when content is retrieved with some device entities (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Esto es lo que se está reproduciendo en la televisión	tv.vod_epg_information plugin	Use case-specific
`tv:carousel.info.contentDetail`	Resource returned when content is retrieved without any device entity (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Aquí tienes más detalles	tv.vod_epg_information plugin	Use case-specific
`tv:tv.moreInfoTvNotAllowed`	No resource returned when content is retrieved with some device entities (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Vaya, parece que no puedo darte más información de lo que estás viendo en la televisión	tv.vod_epg_information plugin	Use case-specific
`tv:tv.more_info.notAllowed`	No resource returned when content is retrieced without any device entity (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Vaya, parece que no puedo hacer eso	tv.vod_epg_information plugin	Use case-specific

Docs:

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

Aura Bot object, data types and models

Description of the different types of data and models supported by Aura Bot

aura-bot supports several data models, compatible with different languages or structures in order to execute the conversational flow.

The current document includes the description of the different models supported by Aura Bot platform, currently:

auraCommand model
The use of auraCommands, that is, pre-defined options that the user can select from Aura’s interface, is managed by the auraCommand model.

dialogContext model
Aura supports the dialogContext model, a structure that facilitates the recognition of CardActions and prompts without the need of training.

Aura API Key
Aura counts on API Keys to connect to available API endpoints. They are based on an encrypted APIKey data model, which is included in aura-validate-apikey utility.

Docs:

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

Error messages v2

Description of errors messages response format

Introduction

When an error happens in a use case in channelData version 2 or higher, it is necessary to set the error in the context status.

const status: AuraResponseStatus = new AuraResponseStatus(AURA_STATUS.ERROR.OTHER.GENERAL, 'Error Whatsapp');
ContextUtils.setStatus(stepContext.context, status);

The activity will be sent as usual.

This is an example of an error when a use case sends a file.

    const status: AuraResponseStatus = new AuraResponseStatus(AURA_STATUS.ERROR.FILE.ERROR_GENERATE_SAS_URL, 'Error Whatsapp file retrieval');
    const attachment: Attachment = {
        contentType: 'application/vnd.telefonica.aura.file',
        content: {
            url: null,
            fileName: null
        }
    };
    const activity: Partial<Activity> = {
        type: 'message', attachments: [attachment],
        inputHint: InputHints.AcceptingInput,
        channelData: {}
    };
    ContextUtils.setStatus(stepContext.context, status);
    await stepContext.context.sendActivity(activity);

All error status are defined in https://github.com/Telefonica/aura-bot-common/blob/master/src/models/aura-status/aura-status-codes.ts

Docs:

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

Aura Bot formats

Description of the different response message formats supported by Aura Bot

By default, aura-bot uses Directline protocol to send the responses to the channels.

But it contains different response formats depending on the channel, to be able to deliver the responses in the most appropriate way for each channel.

The current available formats for Aura responses are:

For information regarding which channelData version is returned in Aura response, check the document Version in responses

Docs:

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

Version in response messages

Table to show if the version is returned in channelData according to some parameters

Table

Channel Id in incoming channelData?	Valid auraId?	LegacyUC set version?	Input version	Message returned by
-	-	-	3	aura-bot & aura-groot
-		(MH UCs)	1	aura-bot
-		(Normal UCs)	1	aura-bot
		-	1	aura-bot
		-	1	aura-groot

If any field is empty in any row, it means that this value does not affect to the final result.

Docs:

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

Global resources for TV use cases

This document describes the global resources shared among global TV use cases

Introduction

Apart from the specific resources for each TV-related use case, there are two types of global resources that can be used by any global experience for TV channels, which are described below:

Aura Platform global resources
Common resources for video use cases

Aura Platform global resources

The Aura Platform global resources that can be used by global TV experiences are:

Aura Platform Global resources	Definition	Example	Managed by	Scope
`core:core.model-validation.request.error`	Error generated in the validation of input fields of the request-response v3 model	Lo siento, ha ocurrido un error inesperado	aura-bot	Used by all Aura global use cases
`core:core.model-validation.answer.error`	Error generated in the validation of output fields from the request-response v3 model	Lo siento, ha ocurrido un error inesperado	aura-bot	Used by all Aura global use cases
`core:core.cancel`	Error generated when the request is adapted to normalized format but the triggered dialog is not migrated to v3	Vaya, parece que no soy capaz de entenderte. Inténtalo de nuevo	aura-bot	Used by all Aura global use cases
`core:core.model-validation.version.error`	Error generated when the request is sent with a format version not supported by the channel	Lo siento, ha ocurrido un error inesperado	aura-bot	Used by all Aura global use cases
`core:flc.answer.error`	Error generated by aura-bot in case the CLF API does not respond	Lo siento, ha ocurrido un error inesperado	aura-bot	Used by Aura global use cases using the Complex Logic Framework

Common resources for video use cases

The general video use cases resources that can be used by global TV experiences are:

Common resources for video use cases	Definition	Example	Managed by	Scope
`tv:video.model-validation.request.error`	Error generated when the input request validation fails	Algo no ha ido bien, inténtalo de nuevo	CLF	Used by global video use cases
`tv:video.api.answer.error`	Error generated when API request fails	Lo sentimos, ha ocurrido un error inesperado	CLF	Used by global video use cases

Docs:

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

Adapter request-response model v1 to v3

This document describes the adapter use cases with request-response model v1 and v3.

Introduction

Adapter use cases allow to work with request-response model v1 to adapt to systems that do not support v3 yet.

Mainly, this adapter receives a request in v1 format and internally transforms it to v3 format to process it with the corresponding TV CLF plugin. Then, the response in v3 format is transformed back to v1 format to send the response.

Dialog Configuration

Specific configuration

The adapter use case is triggered by the generic dialog v1. For this use case, the required specific configuration is set below:

Configuration for Spain OB in STB channel.

{
    "id": "generic-dialog-v1",
    ...
}

Adapter use cases

The adapter use case is intended to work with the following TV use cases: