Aura – communication-protocol

Docs:

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

channelData v3

Specification for channelData v3 model used by Aura Groot and skills to work with the different channels

Introduction

In channelData normalized version (version 3), both request and response follow the rules defined by Microsoft Direct Line v3.

Therefore, the type of message expected both from the channel and from the skill is an Activity of Direct Line.

channelData normalized version (version 3) is an enriched version of channelData that includes new fields with a complete schema definition, that will enforce all the channels to use the very same schema to access Aura.

Find detailed information regarding channelData v3 model in the following documents:

Docs:

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

Communication protocols for channels in Aura

Description of the communication protocols that channels can use to communicate with Aura

Introduction

Channels can talk with Aura through two different communication protocols: Microsoft Direct Line and Auraline or through any aura-bridge adapter.

On one hand, Aura platform is based on Microsoft Azure Bot Service and Bot Framework and leans on the mechanisms, SDK, tools, and techniques provided by this bot engine to implement intelligent bots.
Microsoft Azure Bot Service allows the integration of different channels used by final users to interact with bot instances through a general-purpose communication mechanism called Direct Line API.
Channels can use this protocol through the Aura Request – Response Semantic Model, within the channelData property, used by Aura to define the model in any of the available versions: v1, v2 or the normalized one v3.

Find detailed information regarding Direct Line communication protocol
On the other hand, Aura Platform Team has developed a new communication protocol: Auraline. It is based on Direct Line but with significant advantages as it is a proprietary one and, consequently, eliminates the dependency on Microsoft.
Channels can use this protocol through the Aura Request – Response Semantic Model, within the version v3 of the channelData property.

Find detailed information regarding Auraline communication protocol
Other channels that do not support Direct Line (and consequently, Auraline) will be able to connect to Aura through aura-bridge adapters. This is the case of WhatsApp and Google RCS channels. These adapters “translate” the information coming from the channel to a language Aura can understand. The adapters are provided by aura-bridge and are based on the last version of the standard Aura request/response model.

Flowchart of general scenario regarding communication protocols in Aura

The feasible scenario for channels to communicate with Aura is schematically shown below:

Aura communication protocols:
Communication through Direct Line, Auraline or aura-bridge channel adapter

Auraline communication protocol is firstly conceived for a call center that aggregates different individual channels (call-center as a service), due to Direct Line limitations to manage this scenario. See details in the section Specific scenario for the use of Auraline communication protocol: CCaaS.

Docs:

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

Direct Line communication protocol

Description of useful concepts to understand the Microsoft Direct Line protocol used by channels to communicate with Aura

Introduction

Aura platform is based on Microsoft Azure Bot Service and Bot Framework. Both provide tools to build, test, deploy, and manage intelligent bots all in one place. Through the use of a modular and extensible framework provided by the SDK, tools, templates and AI services, developers can create bots that use speech, understand natural language, handle questions and answers, and more.

One of the key capabilities of the Microsoft Azure Bot Service and Bot Framework is the integration of channels the final users can use to interact with the concrete bot instances implemented using this service and framework. This way, no matter which channel the final users interact with a concrete bot instance, they all are able to establish intelligent conversations with the bot.

Since the aura-groot leans on the Microsoft Azure Bot Service and Bot Framework, channels that use Direct Line communication protocol can “talk” to Aura and integrate with it, becoming Aura custom channels.

Direct Line API

The Microsoft Azure Bot Service exposes a general-purpose mechanism that channel developers can use when implementing or integrating new channels. This general-purpose communication mechanism is called Direct Line API.

The Direct Line API exposes a Web endpoint or URL of a service hosted in the Microsoft Azure cloud that channel developers can use to send messages directly to concrete instances of bot engines hosted in the Microsoft Azure Bot Service. This way, the Direct Line API provides a link between any third-party software component or application, typically used by the final user, and the concrete instance of the bot engine she may be willing to interact with.

Typically, channels accessing through Direct Line to a bot send their requests calling the POST HTTP method of the /conversations/activities endpoint and, as it is an asynchronous API, read the responses from a WebSocket, which URL is obtained when requesting the token to access de API.

The general-purpose communication means exposed by the Direct Line API constitutes an additional mechanism channel developers and integrators can use to create as well as to integrate new channels Telefónica clients can use to interact with Aura. Thanks to it, any communication means can be integrated as an Aura channel.

The only thing which is needed is the proper transformation of the messages coming in and out of the concrete communication means as HTTP messages sent and received through the Direct Line API endpoint available at the Microsoft Azure cloud. This procedure is depicted in the following figure:

How to obtain a valid Direct Line token for Aura Groot

The objective of this document is to explain how an Aura’s channel might access the API that allows generating a Direct Line token valid for an Aura’s environment.

Channels are required to use tokens to communicate with Direct Line API. Each of those tokens is valid for one conversation (and one user) and until it expires (usually in one hour). If further interaction is required after the expiration, the token must be refreshed (get a new fresh version of the token with a later expiration time, calling directly to Direct Line API) before the previous valid token is expired. More information about token refreshing can be found in Direct Line documentation.

The first Direct Line token for each conversation must be obtained from aura-authentication-api. To use this API, a valid Aura APIkey is required:

For integration environments, please ask it to Aura Global Operation Team.
For preproduction and production environments, the OB Operation Team should provide it.

The API definition can be found in section Directline Token in aura-authentication-api. Note that there are two ways to ask for a token, one to get only the token (/token), and another one to get also the stream URL (/token/wss), this is the recommended one as it includes the WebSocket stream URL in the response.

The corresponding Operations Team should also provide the specific domain names where this API is published in each environment.

Request examples

Token only:

curl -X GET \
  https://svc-<env>.auracognitive.com/aura-services/v1/token \
  -H 'Authorization: APIKEY <YOUR-API-KEY>' \
  -H 'correlator: <CORR_UUID>' \
  -H 'cache-control: no-cache'

Token with web socket:

curl -X GET \
  https://svc-<env>.auracognitive.com/aura-services/v1/token/wss \
  -H 'Authorization: APIKEY <YOUR-API-KEY>' \
  -H 'correlator: <CORR_UUID>' \
  -H 'cache-control: no-cache'

Note that correlator header is optional, but it is convenient to send it, to track requests when it is necessary.

Response examples

These responses are returned by Direct Line servers and passed directly to the channel. The value of the field expires_in depends on what is returned by Direct Line, and it could have any numeric value, mainly 1800 or 3600.

The examples contain developed tokens already expired, so they cannot be used in real environments. A request with a valid APIkey must be done in order to get a real valid token.

Token only:

{
  "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJodjRaemR0eXI1OXA3R1BSMEsycmhIUmJuUTQiLA0KICAieDV0IjogImh2NFp6ZHR5cjU5cDdHUFIwSzJyaEhSYm5RNCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogIkJPVC1hdXJhLWFwLW5leHQiLA0KICAic2l0ZSI6ICJfLTJWLU9ocVl2NCIsDQogICJjb252IjogIklHUDR1N1VqR3V1SDA2TmZTSWV2dHktZXUiLA0KICAibmJmIjogMTY0OTc0NjA4MSwNCiAgImV4cCI6IDE2NDk3NDk2ODEsDQogICJpc3MiOiAiaHR0cHM6Ly9kaXJlY3RsaW5lLmJvdGZyYW1ld29yay5jb20vIiwNCiAgImF1ZCI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iDQp9.eZKIPviIA5WwtXPh3LEhD5je1bRR3svGom6KjhwKZpjv4HMCDmblspQSJ-Ax3G51jsZyU_NZM1HRvLweyfBC3TixlIPnLLQ2j55-ZUGQobVTVop84H3QRhUE13GwYPVrvgr_tRsqPTLlUMd7O9zpk5mZ_T-esMQXBwB51izTHRLExFAwDc1jIjV-FWJAQt6ROEZIqWJAMQ6WKuCsm1HXaa0NbCASq90cdZJZc_hyDeengrFklcIiXuzcoFYs3SNKBMCiYuHAWgYGWT6aHpWvreCjEo2VdkcJYkpweaBeagFRzftE3tyzDsb_QrNMrxrWuu5OXPi4j0r7avivL3ap-w",
  "expires_in": 3600
}

Token with web socket:

{
  "conversationId": "Da8BzFBhRMbDpcEN8mjqdn-eu",
  "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJodjRaemR0eXI1OXA3R1BSMEsycmhIUmJuUTQiLA0KICAieDV0IjogImh2NFp6ZHR5cjU5cDdHUFIwSzJyaEhSYm5RNCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogIkJPVC1hdXJhLWFwLW5leHQiLA0KICAic2l0ZSI6ICI4bVJVUmZyMEVxYyIsDQogICJjb252IjogIkRhOEJ6RkJoUk1iRHBjRU44bWpxZG4tZXUiLA0KICAibmJmIjogMTY0OTc0ODU4OCwNCiAgImV4cCI6IDE2NDk3NTIxODgsDQogICJpc3MiOiAiaHR0cHM6Ly9kaXJlY3RsaW5lLmJvdGZyYW1ld29yay5jb20vIiwNCiAgImF1ZCI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iDQp9.wGpPdShRoHf3M7zlTJO9nHyxD8bWF-3JeM7gd0BtrFLDCVEznO1j9Y2ovzRxmeJL8l4xo7T5tH538jAivexelpDb3VET7UvrhZVTNa19J7oOL-eqGtbspYoKp_2xzVNxm2w2lB5cRZVMfyzlvLptfx_-BD2XeohbYGbl_pnmLe6N-490h1S5bE613t1p4bYD1bPA0IKeGhhaiUUBMcA5mCO84eurYesLECAz3T5mCgLP2Xfq7FCeiFmxO4DiEZujKh5FSKd9Gp076ADHdIxxilvKdTFlXykx_v4-yx0xm8YoyHChyRIF9hEzX4dm6hsWLYsgCiM-t60I32_KSRJWxg",
  "expires_in": 3600,
  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/Da8BzFBhRMbDpcEN8mjqdn-eu/stream?watermark=-&t=ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJodjRaemR0eXI1OXA3R1BSMEsycmhIUmJuUTQiLA0KICAieDV0IjogImh2NFp6ZHR5cjU5cDdHUFIwSzJyaEhSYm5RNCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogIkJPVC1hdXJhLWFwLW5leHQiLA0KICAic2l0ZSI6ICI4bVJVUmZyMEVxYyIsDQogICJjb252IjogIkRhOEJ6RkJoUk1iRHBjRU44bWpxZG4tZXUiLA0KICAibmJmIjogMTY0OTc0ODU4OCwNCiAgImV4cCI6IDE2NDk3NDg2NDgsDQogICJpc3MiOiAiaHR0cHM6Ly9kaXJlY3RsaW5lLmJvdGZyYW1ld29yay5jb20vIiwNCiAgImF1ZCI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iDQp9.ctcwxvoyi8EdSee3x3TOogvy8puphmpsn8wouTaPZzFaVFb4YcuE-336e4bg99uCPffHAlVPLBc8xpVjeM4JdDQWncO-TpPFlj7fM_x_YmunlVLS4OsNspnMQ9lUgn6FLBD9GUdJ5GRySOltrDbsoHI0EMaljs2ni6b8ZQ9LKFdY8QyAKRqS9Eto1_MCiPmuseM_KM8VtL2fZMmhzwfhxf7dOHbEtu121Nj8LTxZTNI1f5gpKsEuw6neX1g7MQyrD-ajr0s-hD90g5r79vQvompVzFf3LgoXsMdKLIgz8PkVg6hIJwQFIC4piSHV7--g8k-alJ-XMspNGBCeD3dVfw",
  "referenceGrammarId": "f4d20b6f-6e5c-175e-abdf-e9eb65e5d058"
}

API errors handling

The aim of this endpoint is to allow the channels to obtain a valid token to access Direct Line API without sharing the primary keys of the bot with all of them. So, basically, the endpoint just wraps the requests to Direct Line API, this includes that all the errors returned by Direct Line API are returned to the caller.

Status Code	Meaning	Recommended action
400	Error in the request. It could be an error in the request of the channel to Aura, or in Aura’s request to Direct Line.	Validate the request being launched. If it seems to be ok, request a validation of the logs in the corresponding Aura environment.
401	Invalid credentials. It could be an error in the APIKey or in the aura-authentication-api configuration.	Validate if your APIKey is valid. Request a validation of the logs in the corresponding Aura environment.
429	Too many requests. Direct Line service is having too many requests to get a valid token for this bot.	An exponential backoff system must be implemented to avoid making the situation worse. So, you should wait for 30 seconds before launching a new request. If this gets a 429 again, you should wait for 1 minute, then 2 minutes, etc. Consider that in order to avoid this situation, all the requests of your users must be taken into account all together.
500	Internal error.	Wait for the server to recover, but request to Aura Operations Team of the environment the resolution of the issue.

Only the body and the status code of the response of Direct Line are returned to the caller, none of the headers are included.

Using the token: calling Direct Line API

HTTP GET requests made by the channel (to send or receive activities) will be authorized by a token (the first one, or after refresh) through the Authorization header, for instance:

POST https://directline.botframework.com/v3/directline/conversations/<CONV_ID>/activities
Authorization: Bearer <YOUR_TOKEN>

To get activities through a web socket, the channel must use the stream URL obtained in /token/wss. The token is sent in t param, and it will expire after one minute after the token request.

Once connected the web socket, it will get activities for one hour. After that time, a new token (through refreshing) and a new web socket connection are required, setting the fresh token within the t param in stream URL, for instance:

wss://directline.botframework.com/v3/directline/conversations/<CONV_ID>/stream?watermark=-&t=<NEW_TOKEN>"

Note that refresh token must be obtained before current token is expired.

Full communication flow

The flow to get the first token, and optionally refresh it, for conversations longer than one hour, is as follows:

sequenceDiagram

Channel ->> Auth API: Get Wss token (API key)
Auth API ->> Direct Line: Start conversation (app token)
Direct Line ->> Auth API: {conversationId, token, expires_in, streamUrl}
Auth API ->> Channel: {conversationId, token, expires_in, streamUrl}
loop send / receive activities during one hour
  Channel -->> Direct Line: POST /conversation/activities (token)
  Direct Line -->> Channel: [activities]
end

alt refresh token
  Channel ->> Direct Line: Refresh (token)
  Direct Line ->> Channel: new_token
  loop send / receive activities during one hour
    Channel -->> Direct Line: POST /conversation/activities (new_token)
    Direct Line -->> Channel: [activities]
  end
else
  Channel -->> Direct Line: POST /conversation/activities (token)
  Direct Line -->> Channel: Token expired (403)
end

Note that the sending of activities from Direct Line to the channel may be through a web socket (if opened) or HTTP GET request from channel.

Docs:

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

Aura request semantic model v3

Version v3 of Aura request semantic model description

Introduction

The Aura Request Semantic Model defines the set of properties that can be included in the channelData property of the request activities sent from the Telefónica client side (channel) to the skills through aura-groot.

The properties of the Aura request semantic model corresponding to the v3 normalized version can be grouped into two categories:

JSON schema for the Aura request semantic model v3

The root channelData properties are included in the JSON schema for channelData v3 request model
Root channelData payload property

The fields included in the payload property are defined in the section Root channelData payload property

Root channelData payload property

The payload property can be used by an external component to facilitate the sharing of information between the channels, aura-groot and the skills in order add extra information associated with the channel and, consequently, enrich the request.

The full content of channelData.payload will be sent from aura-groot to the skill, but the skill MUST send it back to aura-groot, without removing anything.

The skill can only add two fields, that are explained below: channel and skill:

channel is an optional open field, where the skill can share metadata with the channel. In Auraline, an external component can share metadata with the skill and/or get that information in the response.
skill is an optional but recommended field that must be fulfilled by the skill to inform aura-groot about the user’s intention recognized by the skill.

Currently, the payload property is used by components that interact with aura-groot through aura-bridge, but it could be used by any component. Moreover, this field is used in the interaction between aura-groot and skills.

The payload model is valid for every channel’s request-response version: v1, v2 and v3.

{
    "type": "message",
    "text": "Hello!",
    ...
    "channelData": {
        "payload": {
            // Extra channel information
        }
    }
}

Model definition

The complete model definition is located in the @telefonica/aura-utilities/lib/aura-models library (git repository: aura-models)

In the resources/channel-data folder of that repository, there is a scheme file with the definition in json schema format.

How to use the payload model

In order to use specific information from a channel (or communication that uses aura-bridge), certain steps are required:

Define the property name that will be sent in channeldata.payload.
Define the data model in aura-models.
Add/use the channelData.payload information in the different Aura components.

Model information

channelData payload information property can be used by an external component to aura-groot in order to send information for the enrichment of the request. The information sent does not correspond to the Bot Framework communication model, but it is used by aura-groot and certain dialogs to complete processing. Currently it is used by components interacting with the bot through aura-bridge, but it could is used by any component.

The following table and sections below shown the current parameters defined in the payload:

Property	Type	Description
bridge	Bridge	Information sent from aura-bridge
handover	Handover	Information sent from Handover
event	PayloadEvent	Information sent as an event
asyncCallback	any	Payload received in an async callback notification. The format is defined by the calling API. Only the dialog in charge of handling the request must validate the format
auraGroot	AuraGrootPayLoad	Information sent from aura-groot to the skill

Bridge

Object with relevant information sent from aura-bridge.

Property	Type	Description
accessToken	string	Bridge access token
answersCallback	string	URL to which the bridge will send the request back
channelId	string	ChannelId information
params	any	Open params
template	Template	Template information
user	BridgeUser	Information associated to the user who uses the bridge
whatsapp	Whatsapp	Information associated with the WhatsApp channel
resetGrootConversation	Boolean	Flag to indicate aura-groot that must create a new conversation with the skill
referral	any	Object that contains the whatsapp referral info

BridgeUser

Bridge user information

Property	Type	Description
name	string	Name associated with the user who makes the request to aura-bridge

BridgeUserName (Enum)

Enum for BridgeUserName

Property	Type	Description
System	system	Username used by aura-bridge

Template

Template information

Property	Type	Description
namespace	string	Namespace where the template is
name	string	Template’s name
language	string	Template’s language
parameters	ParametersTemplate	Template’s parameters

ParametersTemplate

ParametersTemplate information

Property	Type	Description
header	string[]	Parameters for header template
body	string[]	Parameters for body template
button	CommandTemplate or string	Parameters for buttons

CommandTemplate

CommandTemplate information

Property	Type	Description
intent	string	Intent associated to button
entities	any[]	Entities associated to button

Options to configure the WhatsApp channel in aura-bridge.

Property	Type	Description
listOptions	ListOptions	It defines the conversion of prompts and suggestions that use HeroCard to WhatsApp lists.
allowEmpty	boolean	It indicates whether the texts of each of the messages received can be empty. By default: `false`
textConvert	boolean	It indicates whether the texts of each of the messages received must be converted to the WhatsApp markdown format. By default: `true`

ListOptions

It defines the conversion of prompts and suggestions that use HeroCard to WhatsApp lists.

Property	Type	Description
type	ListOptionsType	Whatsapp list type
rules	ListOptionsRule	Conversion rules to whatsapp lists

ListOptionsType (Enum)

Enum for ListOptionsType

Property	Type	Description
Button	button	Reply Buttons. Messages including up to 3 options
EnumeratedList	enumeratedList	Enumerated text list
List	list	List Messages. Messages including a menu of up to 10 options

ListOptionsRule

Conversion rules to WhatsApp lists

Property	Type	Description
type	ListOptionsType	WhatsApp list type
resources	Resource	Definition of resources used in the WhatsApp lists

Resource

Definition of the resources used in the WhatsApp lists

Property	Type	Description
name	string	Resource name
resourceKey	string	Resource key (POEditor)

Handover

Object with relevant information sent from the Handover

Property	Type	Description
agentName	string	Handover agent name
participantType	string	Type of participant associated with the event. Example: `system`, `agent`
eventType	string	Event type. Example: `participantJoined`, `participantLeft`
chatEnded	boolean	It indicates whether the chat with the user has ended
quitReasonCode	number	If the chat has ended, this field indicates the closing reason
reasonForLeave	string	Reason associated with the `ParticipantLeft` event (eventType)
genesysCallback	string	Handover URL to which aura-bot must send calls

PayloadEvent

Payload received in an async callback notification

Property	Type	Description
message	string	Message associated with event
status	number	Status associated with event
type	TypeEvent	Event type

TypeEvent (Enum)

Enum for TypeEvent

Property	Type	Description
Log	log	Log event
EmptyResponse	emptyResponse	Direct Line empty response event (Event sent by aura-bot when no response activity is sent)

AuraGrootPayLoad

Information sent from aura-groot to the skill. It is intended to facilitate the handling of activities by a skill. This field is only sent to the skill.

Property	Type	Description
channelConversationId	string	ID of the directlineConversation handled by the channel
channelId	string	Identifier of the channel in Aura
accountNumber	string	AccountNumber from user received in aura-groot
conversationHistory	ConversationHistory	Conversation history of user

ConversationHistory

Information sent from aura-groot to the skill regarding the conversation history of the user.

Property	Type	Description
date	Date	Date of message
id	string	Id of message
type	ConversationHistoryType	Type of message
from	string	From of message
message	string	Message
intentResult	string	Intent result

ConversationHistoryType (Enum)

Property	Type	Description
Request	request	Request type
Response	response	Response type

Payload examples

A complete example of the payload can found here.

Moreover, the example below shows the application of the auraGroot property:

{
    "locale": "en-EN",
    "type": "message",
    "from": {
        "id": "user1"
    },
    "text": "hello",
    "channelData": {
       "appContext": {
           "channel": {
               "id": "ca3f344f-b780-ef52-3c47-81daf07bb3d3",
               "modality": "text"
            }
            "timestamp": "2023-03-01T10:15:30+01:00",
            "timezone": "Europe/Madrid",
            "payload":
                "auraGroot": {
                    "channelConversationId": "<channelConversationId>", // id of the directlineConversation handled by the channel
                    "channelId": "<channelId>", // identifier of the channel in Aura
                }
            }
        },
       "version": "3",
       "correlator": "19d63cd4-8f7e-4194-837d-c55991b1afcd"
    }
}

Docs:

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

Auraline communication protocol

Description of the Auraline communication protocol used by channels to communicate with Aura

Related documents
Guidelines for connecting a channel to Auraline

Introduction

Aura Platform Team has developed a new communication protocol named Auraline. This is a proprietary protocol, developed and exclusively owned by Aura Platform Team for facilitating communication between channels and Aura. Auraline is based on Microsoft Direct Line and can be considered as a local implementation of the Microsoft protocol, eliminating dependencies on Microsoft Azure Bot Service.

This particularity provides significant advantages, including cost saving, higher flexibility and the ability to plan future developments according to our specific needs. Additionally, it enables us to address new backend-to-backend scenarios, such as managing a channels aggregator system or responding across multiple channels or applications instead of a single one.

Auraline facilitates the process for integrating new channels into the communication framework. Moreover, it enables an easy transition for channels that are currently integrated into Direct Line, minimizing disruptions and maximizing interoperability.

Auraline uses Aura request-response semantic model v3, implemented by the normalized version of the property channelData v3.

Communication protocol

Auraline facilitates the communication of a channel with aura-bridge and aura-groot, consequently establishing a connection with the skills connected to aura-groot. To enable this communication, specific plugins and swaggers are developed in aura-bridge to support this protocol.

Given its foundation on the Microsoft Direct Line protocol, Auraline adopts the Direct Line JSON format and integrates the same basic processes as those in Microsoft framework:

Management of conversations and token
- Creation of a conversation: It provides back a conversationId and a token.
- Refreshing of non-expired tokens
Management of sent and received messages
- Sending messages from users to the bot, utilizing the conversationId and the token.
- Sending messages from the bot to users, through the publication by the channel of a callback where these messages are received.
- Sending status of messages to notify the correct reception by the user or an error status.

As previously mentioned, Auraline relies on our request-response semantic model v3. The communication between aura-groot and aura-bridge will always use the single message response format in order to simplify the integration and ensure the orderly delivery of responses to the users.

Responses between aura-bridge and the channel will include an array of activities in a unique answer for each message, that will be orderly delivered to the channel.

The following figure shows the sequence diagram of Auraline communication protocol:

Specific scenario for the use of Auraline communication protocol: CCaaS

The development of Auraline communication protocol is initially aimed at resolving the scenario in which different channels are grouped together in a CCaaS (call-center as a service) that acts as a channel concentrator.

This scenario is schematically shown in the following figure:

Docs:

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

channelData v2

Specification for channelData v2 model used by Aura Bot to work with the different channels

Introduction

channelData is an open field in the activity, i.e., the message exchanged during a communication between a channel and a bot built on top of Microsoft BotFramework, that is devoted to define the specific format of the request needed by the bot to provide a proper response to the channel and thus to the user.

In Greenday Aura Platform release, channelData model was updated to version v2. This model was based in v1 version but including some extra features such as status in the bot response. This field represents how the request made to Aura has worked, trying to summarize if it has been successful or it has failed and the reason for it.

Check the statuscode here

JSON schema for channelData v2 request model

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "resource:/aura-models/channel-data/1.0.0/request/channeldata-1.0.0-request.schema#",
    "$ref": "#/definitions/aura/bot/1.0.0/request/ChannelData",
    "$version": "1.0.0",
    "definitions": {
        "aura": {
            "bot": {
                "1.0.0": {
                    "request": {
                        "ChannelData": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "fullAura": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/FullAura"
                                },
                                "allowed": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "appContext": {
                                    "description": "This property contains application context data to let the Aura bot instance adapt its response to the characteristics of the application being used by the Telefónica client to interact with Aura. It contains both general properties and specific properties for TV channels.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/AppContext"
                                },
                                "auraCommand": {
                                    "description": "This property makes it possible to send a specific intent to the Aura bot on behalf of the Telefónica client interacting with Aura. Consequently, the message contents do not need to be analysed to recognize the Telefónica client intent.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/AuraCommand"
                                },
                                "auraMode": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/AuraMode"
                                },
                                "customAuraContent": {
                                    "type": "boolean"
                                },
                                "imageMaxWidth": {
                                    "type": "number"
                                },
                                "correlator": {
                                    "description": "This property contains an UUID uniquely identifying the concrete request sent through the channel. This unique identifier is of great help when doing cross system analysis, as a way to correlate the actions executed by distinct elements of the whole system associated to the fulfilment of the same request. In case the correlator property is not provided, the Aura bot will generate one and pass it over in any interaction with any external component.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "dialogContext": {
                                    "description": "This property must only be included in the request every time the previous response from the AuraBot contains a dialogContext. The channel would just copy the very same object in its following request to AuraBot. The dialogContext contains extra information to contextualize the next request as part of a whole conversation (even as part of a set of conversations) so Aura bot is able to behave in a much more similar way to human's behaviour when establishing and maintaining conversations. If the dialogContext property is set in the request, it will be used during the bot recognition phase to find the intention of the user directly. It is as a hidden menu for the dialog being executed that allows extra straightforward recognitions.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/DialogContext"
                                },
                                "imageSettings": {
                                    "description": "This property makes it possible to provide information about the graphical screening capabilities exposed by the application used by the Telefónica client to interact with the Aura bot instance. The contents of this property are typically used to optimize the graphical content sent by the Aura bot instance to the application finally showing the graphical information sent.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/ImageSettings"
                                },
                                "version": {
                                    "description": "This property encodes the version of the Aura Request – Response Semantic Model being used, so the structural dependencies and semantics of the data provided can be properly managed.",
                                    "type": "string",
                                    "pattern": "^[0-9]+.[0-9]+.[0-9]+$"
                                }
                            },
                            "required": [
                                "appContext",
                                "dialogContext",
                                "version"
                            ],
                            "title": "ChannelData"
                        },
                        "FullAura": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "voice": {
                                    "type": "boolean"
                                },
                                "fullScreenAdvisor": {
                                    "type": "boolean"
                                },
                                "cards": {
                                    "type": "string"
                                }
                            },
                            "title": "FullAura"
                        },
                        "AppContext": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "application": {
                                    "description": "This property includes information about the characteristics of the application being used by the Telefónica client to interact with the Aura bot instance. Also generally speaking is Optional (but recommended). It contains both general sub-properties and specific ones for TV channels In Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Application"
                                },
                                "channel": {
                                    "description": "This property includes information about the channel being used by the Telefónica client to interact with the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Channel"
                                },
                                "device": {
                                    "description": "This property includes Information about the physical device used by the Telefónica client to interact with the Aura bot instance. Also generally speaking is optional (but recommended). In Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Device"
                                },
                                "location": {
                                    "description": "This property includes information about the location where the user is located. Also generally speaking is optional (but recommended). In Spain, it is a mandatory parameter for TV use cases, if not sent logical.unknown location will be used.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Location"
                                },
                                "userContext": {
                                    "description": "[TV] This property includes information about the user associated to the Telefónica client interacting with the Aura bot instance. This information can be used to customize the response sent back by the Aura bot instance to the specific Telefónica client. Although generally speaking, this parameter is optional.  It is a general property, but for the current model, it is only applied for TV use cases. In fact, in Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/UserContext"
                                },
                                "contextFilters": {
                                    "description": "This property includes information in a string array format which may be used to filter the final response sent by the Aura bot instance back to the Telefónica client. For example, to determine the most appropriate answer to a generic question. The format of each entry of the array should be key:value, where both key and value are application dependant.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "timestamp": {
                                    "description": "This property includes an ISO 8601 formatted string with the exact local time instant when the request was sent. It should contain the local time including the corresponding time zone.",
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "timezone": {
                                    "description": "This property includes the time zone from where the Telefónica client is interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "livingApp": {
                                    "description": "[LA] This property includes the time zone from where the Telefónica client is interacting with the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/LivingApp"
                                }
                            },
                            "required": [
                                "channel"
                            ],
                            "title": "AppContext"
                        },
                        "Application": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "playMode": {
                                    "description": "[TV] For the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player (such as a TV), this property states if the access if being made by the concrete media player device or by an external app where the content is embedded and played.",
                                    "type": "string",
                                    "enum": [
                                        "LOCALE",
                                        "REMOTE"
                                    ]
                                },
                                "type": {
                                    "type": "string"
                                },
                                "playing": {
                                    "description": "[TV] This property includes information about the content being played for the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player such as a TV or a channel abled to be linked with a TV.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Playing"
                                },
                                "screenId": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/ScreenId"
                                }
                            },
                            "title": "Application"
                        },
                        "ScreenId": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "type": {
                                    "type": "string"
                                },
                                "ucid": {
                                    "type": "string"
                                },
                                "vod": {
                                    "type": "boolean"
                                }
                            },
                            "title": "ScreenId"
                        },
                        "Playing": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "id": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: - false, if the content cannot be recorded. (unique possible value if 'type' is VoD) - true, if the content can be recorded.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "Type of content being played.",
                                    "type": "string",
                                    "enum": [
                                        "live",
                                        "vod",
                                        "l7d",
                                        "record"
                                    ]
                                },
                                "recordingAllowed": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: - false, if the content cannot be recorded. (unique possible value if 'type' is VoD) - true, if the content can be recorded.",
                                    "type": "number"
                                },
                                "startOver": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: - false, if the content cannot be recorded. (unique possible value if 'type' is VoD) - true, if the content can be recorded.",
                                    "type": "number"
                                },
                                "currentAudioID": {
                                    "description": "This property states the audio language selected by the Telefónica client to play the associated content. The value of this property must be one of the keys included in the audioList property.",
                                    "type": "string"
                                },
                                "currentSubtitlesID": {
                                    "description": "This property states the subtitles language selected by the Telefónica client to play the associated content. The value of this property must be one of the keys included in the subtitlesList property. If no subtitles are selected, this property should not be included.",
                                    "type": "string"
                                },
                                "audioList": {
                                    "description": "This property includes an object whose values are 3-letters codes (ISO 639-2) stating the available audio language.",
                                    "type": "object"
                                },
                                "subtitlesList": {
                                    "description": "This property includes an object whose values are 3-letters codes (ISO 639-2) stating the available subtitles language.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "type",
                                "id"
                            ],
                            "title": "Playing"
                        },
                        "Channel": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "appId": {
                                    "description": "This property includes a unique identifier in UUID format which uniquely identifies the channel in Aura. The UUID is the same for all OBs. This identifier must be provided by Aura Operations Team to the channel.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "modality": {
                                    "description": "This property describes the way the Telefónica client used to interact with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "AUDIO",
                                        "VOICE",
                                        "TEXT",
                                        "TACTILE",
                                        "COMMAND",
                                        "FORM"
                                    ]
                                }
                            },
                            "required": [
                                "appId",
                                "modality"
                            ],
                            "title": "Channel"
                        },
                        "Device": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "deviceId": {
                                    "description": "This property includes a unique identifier of the device the Telefónica client used to interact with the Aura bot instance. This id must be already registered in the backends of the OB.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "This property states the type of device used by the Telefónica client used to interact with the Aura bot instance. The possible values should be aligned with the APIs backend to ensure that contents will be returned.",
                                    "type": "string"
                                },
                                "interfaceLanguage": {
                                    "description": "This property includes a combination of ISO-3166 2-letters country codes and ISO 639-1 2-letter language code separated by a hyphen stating the language used by the Telefónica client to interact with the concrete Aura bot instance.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "deviceId",
                                "type"
                            ],
                            "title": "Device"
                        },
                        "Location": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "logical": {
                                    "description": "This property describes the location from where the Telefónica client interacts with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "home",
                                        "outside",
                                        "unknown"
                                    ]
                                }
                            },
                            "title": "Location"
                        },
                        "UserContext": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "userAccountNumber": {
                                    "description": "This property includes an identifier uniquely identifying the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "userProductList": {
                                    "description": "This property includes a list of the products available in the active contract for the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "userProfile": {
                                    "description": "This property describes the commercial offer chosen by the Telefónica client interacting with the Aura bot instance. This property only applies in the case of Spain for STB, Movistar Home and Movistar Plus channels.",
                                    "type": "string"
                                },
                                "userPurchaseList": {
                                    "description": "List with the content purchased by the user (tVOD).",
                                    "type": "string"
                                },
                                "userSTBList": {
                                    "description": "This property includes the list of STBs which belongs to the Telefónica client interacting with the Aura bot instance.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/STBType"
                                    }
                                }
                            },
                            "required": [
                                "userAccountNumber",
                                "userSTBList"
                            ],
                            "title": "UserContext"
                        },
                        "STBType": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "deviceId": {
                                    "description": "This property includes the device identifier of the STB.",
                                    "type": "string"
                                },
                                "model": {
                                    "description": "This property includes the device model of the STB.",
                                    "type": "string"
                                },
                                "friendlyName": {
                                    "description": "This property includes a printable name of the STB device. This can be modified by the user using the STB UI.",
                                    "type": "string"
                                },
                                "remote_play_allowed": {
                                    "description": "This property includes a boolean value (this is, true or false) describing if the STB device allows the possibility of playing content launched from a remote entity such as a mobile application.",
                                    "type": "boolean"
                                },
                                "remote_play_on": {
                                    "description": "This property includes a boolean value (this is, true or false) describing if the STB device is on or off.",
                                    "type": "boolean"
                                },
                                "maxQuality": {
                                    "description": "Highest video quality of the device.",
                                    "type": "string",
                                    "enum": [
                                        "highDefinition",
                                        "lowDefinition",
                                        "standardDefinition",
                                        "UHD_4K"
                                    ]
                                }
                            },
                            "required": [
                                "deviceId"
                            ],
                            "title": "STBType"
                        },
                        "LivingApp": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "id": {
                                    "description": "This property includes an identifier uniquely identifying (UUID) the Living App in Aura.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "description": "This property includes a semantic identifier uniquely identifying the Living App in Aura.",
                                    "type": "string"
                                },
                                "prefix": {
                                    "description": "This property includes the short name associated to the Living App",
                                    "type": "string"
                                },
                                "sessionId": {
                                    "description": "This property includes an identifier uniquely identifying the session associated to the Living App in Aura. The  sessionId property must be sent if it was previously received in the start-living-appevent response message.",
                                    "type": "string"
                                },
                                "prettyName": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "id",
                                "name",
                                "prefix",
                                "sessionId"
                            ],
                            "title": "LivingApp"
                        },
                        "AuraCommand": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "type": {
                                    "description": "This property includes the type of Aura command sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "intent",
                                        "suggestion",
                                        "notification",
                                        "operation",
                                        "text",
                                        "event"
                                    ]
                                },
                                "value": {
                                    "description": "This property includes the data needed to execute the command. Its content depends on the type of Aura command.",
                                    "anyOf": [
                                        {
                                            "$ref": "#/definitions/aura/bot/1.0.0/request/SuggestionIntentOperationValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/1.0.0/request/NotificationValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/1.0.0/request/EventValue"
                                        },
                                        {
                                            "type": "string"
                                        }
                                    ]
                                },
                                "utm": {
                                    "description": "It shows the exact interface element that was used by the user to launch the auraCommand.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Utm"
                                }
                            },
                            "required": [
                                "type",
                                "value"
                            ],
                            "title": "AuraCommand",
                            "allOf": [
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "pattern": "intent|suggestion|operation"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/1.0.0/request/SuggestionIntentOperationValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "notification"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/1.0.0/request/NotificationValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "text"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "event"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/1.0.0/request/EventValue"
                                            }
                                        }
                                    }
                                }
                            ]
                        },
                        "SuggestionIntentOperationValue": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference which will determine the Aura dialog to execute. The format of this property is: intent.<libraryId>.<intentId> In case the prefix intent. is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: - type:  this property includes a string stating the type of entity. - entity: this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/Entity"
                                    }
                                }
                            },
                            "required": [
                                "intent"
                            ],
                            "title": "SuggestionIntentOperationValue"
                        },
                        "NotificationValue": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "action": {
                                    "description": "This property includes the Aura intention reference informing of the dialog to be executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>.",
                                    "type": "string"
                                },
                                "notificationData": {
                                    "description": "This property includes detailed information about the notification being sent to the Telefónica client. The data sent will let Aura predict unusual behaviour in clients billing, balance or data consumption.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "action",
                                "notificationData"
                            ],
                            "title": "NotificationValue"
                        },
                        "EventValue": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference informing of the dialog to be executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: - type:  this property includes a string stating the type of entity. - entity: this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/Entity"
                                    }
                                },
                                "text": {
                                    "description": "User utterance.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "Event type: local-grammar.",
                                    "type": "string"
                                },
                                "payload": {
                                    "description": "Specific per event type.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "type"
                            ],
                            "title": "EventValue"
                        },
                        "Utm": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "source": {
                                    "description": "It identifies which site sent the traffic. Please, use the channel name.",
                                    "type": "string"
                                },
                                "medium": {
                                    "description": "It identifies what type of link was used, such as cost per click or email.",
                                    "type": "string"
                                },
                                "campaign": {
                                    "description": "It identifies a specific product promotion or strategic campaign.",
                                    "type": "string"
                                },
                                "term": {
                                    "description": "It identifies search terms. We still need to define the content of this field.",
                                    "type": "string"
                                },
                                "content": {
                                    "description": "It identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "source"
                            ],
                            "title": "Utm"
                        },
                        "AuraMode": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "fullAura": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/FullAura"
                                }
                            },
                            "title": "AuraMode"
                        },
                        "DialogContext": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "text": {
                                    "description": "This property includes the word to be recognized. In forthcoming releases of Aura, the contents of this property will be upgraded to a pipe separated list of recognizable words.",
                                    "type": "string"
                                },
                                "value": {
                                    "description": "This property includes the data needed to execute the command.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Value"
                                }
                            },
                            "title": "DialogContext"
                        },
                        "Value": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference which will determine the Aura dialog to execute. The format of this property is: intent.<libraryId>.<intentId>. In case the prefix intent. is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: - type:  this property includes a string stating the type of entity. - entity: this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/Entity"
                                    }
                                }
                            },
                            "required": [
                                "intent",
                                "entities"
                            ],
                            "title": "Value"
                        },
                        "Entity": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "canon": {
                                    "description": " This property includes the canonical form of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "endIndex": {
                                    "description": "The index at which this entity ends in the original user message.",
                                    "type": "number"
                                },
                                "entity": {
                                    "description": "This property includes the value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "label": {
                                    "description": "This property includes an internally used descriptive tag of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "score": {
                                    "description": "This property includes the accuracy (in per 1 units) of the recognized entity sent on behalf of the Telefónica client interacting with the Aura bot instance. In the case of Aura commands this value should be 1 since in this case fully recognized intentions are sent.",
                                    "type": "number"
                                },
                                "startIndex": {
                                    "description": "The index at which this entity starts in the original user message.",
                                    "type": "number"
                                },
                                "type": {
                                    "description": "This property includes the type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance. The format used by this property is the following one: ent.<entityType>",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "canon",
                                "entity",
                                "score",
                                "type"
                            ],
                            "title": "Entity"
                        },
                        "ImageSettings": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "graphicsWidth": {
                                    "description": "his property indicates the recommended width in pixels of the images the Aura bot instance should sent to the Telefónica client according to the communication means she is using to interact with Aura. The default value is 500.",
                                    "type": "number"
                                },
                                "resolution": {
                                    "description": "This property indicates the recommended scaling factor the Aura bot instance should apply to the images sent to the Telefónica client. The default value is mdpi.",
                                    "type": "string",
                                    "enum": [
                                        "mdpi",
                                        "hdpi",
                                        "xhdpi",
                                        "xxhdpi",
                                        "xxxhdpi"
                                    ]
                                }
                            },
                            "title": "ImageSettings"
                        }
                    }
                }
            }
        }
    }
}

Docs:

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

ATRIA RAG Generate DB operational overview

Overview of the atria-rag-generate-db operation

Operational flow

The operational flow between an application (for the communication with aura-gateway-api), atria-model-gateway, atria-rag-server and atria-rag-generate-db is schematically shown in the document atria-model-gateway: operational flow.

Configuration

atria-model-gateway includes a default configuration. Constructors can use it as is or they can modify it to be adapted to their requirements or business models: Go to document ATRIA configuration.

Data persistence feature

Now ATRIA enables data persistence in knowledge bases across releases: After the installation of a new release, all existing data in the knowledge base (currently, Qdrant) remains fully available and accessible for every ATRIA experience. Thus, information is completely independent of the deployed version.

This feature provides key advantages:

Guaranteed continuity of ATRIA experiences.
No need for data re-ingestion after each release.
No need to recalculate embeddings.
Data ingested after the installation of a release (through hot swapping) is now automatically consolidated and carried forward to subsequent releases.

Tracking and clean-up processes

atria-rag-generate-db keeps a record of the current state of documents and related configuration for data sources, so it only feeds documents that have been modified or added since the last update.

atria-rag-generate-db also cleans up any resources that are left behind and no longer used after new ones are introduced.

Preset management

Preset report

After generation-db is executed, a report is logged with the following information for each preset:

The preset name.
The status of the execution (success, skipped or error).
A descriptive message with the reason for the status.
Date and time of the execution start.
Date and time of the execution end.
The configured documents for the preset

Preset availability

When a new preset is created, it is necessary to launch the database generation process by executing the atria-rag-generate-db component. This process may take several minutes to complete. Once the generation is finished, the atria-rag-generate-db component is automatically restarted.

While these processes are running, a message is shown to the user indicating that the preset is not yet available.

When both processes are finished, the preset becomes available for use.

Data migration between ATRIA releases

The data persistence feature is implemented by a migration tool between environments or releases integrated in the atria-rag-generate-db component. This tool moves the trained data from one release to another, to avoid generating preset data that has been previously created in a release.

The process for migrating data must be triggered manually by launching a command (similar to the aura-rag-generate-db job), where both source and target environments should be indicated.

After executing this command, data will be migrated from one environment to the other automatically.

The migration flow is executed as follows:

Process the hashes file and, for each preset we want to migrate, we will do the following steps:
- Check that the preset from the source environment is in the config of the target environment
- Move the trained_data files from the source environment to the respective training folder of the target environment
- Duplicate the collections from the source environment to the target environment
- Move the TFIDFs files from the source environment to the target environment
Move the hashes file from the source environment to the target environment
Add the new presets training files to the respective training folder in the target environment.
Launch atria-rag-generate-db. Only new presets will be reloaded.

Data migration flow

In the migration process described above, the following folders are generated and stored in an Azure blob storage after atria-rag-generate-db is finished:

Shared data

This folder contains the trained data shared between atria-rag-server and atria-rag-generate-db. This is used to store the files that the atria-rag-generate-db generates and then the atria-rag-server uses to be able to process the request.

At the moment, only the files generated by the TFIDF (Term Frequency–Inverse Document Frequency) exist in this folder.

This folder is used for migration, as we can take the TFIDFs of a trained preset to the blob of a specific release where that preset has not been trained and save the training afterward.

Trained data

This folder contains the files that have been used in the atria-rag-generate-db for each preset.

The folder structure is defined with a hash of the contents of all the files for each preset, to facilitate migration.

Atria RAG project hashes

This is a file containing all the information for each preset, to facilitate migration.

It contains the following information for each preset:

config_hash: Hash of the preset configuration at the time the atria-rag-generate-db was launched.
source_files_hash: Hash of the source files used to generate the preset. This hash should exist in one folder into the trained data folder.
metadata: Metadata of the preset, including the date of atria-rag-generate-db launching.

retrievers: Info that retrievers used to generate the preset. It contains the name of the Qdrant collection and the path where it holds the TFIDF files, which would correspond to the shared data.

{
  "5905dece-433d-47f4-a78c-72366bcd1473": {
    "config_hash": "28f837d56079f30c59a419292d129bc3",
    "source_files_hash": "cda3afcd8e74ede0d23065e897d55fae",
    "metadata": {
      "date": "2025-04-01 11:25:59"
    },
    "retrievers": {
      "qdrant_collection_name": "rag-ap-eight-9100-dev-project-copilot",
      "tfidf_path_file": "project-copilot/tfidf"
    }
  }
}

In addition to using this data for migration, it also speeds up the launch of the atria-rag-generate-db.

The config_hash and source_files_hash values are used to verify if, at the moment of launching the atria-rag-generate-db, something has been changed in the configuration or in the training data. If changes are detected, all the data for that preset is regenerated. Otherwise, if the preset has not changed, we will save that generation.

Launch migration process

The process to persist data between releases has to be launched manually through the execution of the following command: To run this script, we just need the output files with the environment configuration info generated by the installer in the output_install directory from the source and destination environment. With this info, run the script as shown below, using the corresponding files names for the desired environment:

  ./migrate-data --source-file ${SOURCE_ENVIRONMENT_INFO_FILE} --dest-file ${DEST_ENVIRONMENT_INFO_FILE}

Where:

source-file: Source environment info file where the data is stored.
dest-file: Target environment info file where the data is going to be migrated.

Docs:

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

Aura response semantic model v3

Version v3 of Aura response semantic model description

Introduction

The Aura response semantic Model defines a set of properties which can be used as children of the Microsoft Azure Bot Service and Bot Framework activities channelData property included in the response activities.

Although the request and response models have some common fields, they are indeed different, so pay attention to both definitions.

The Aura response semantic model includes two properties: channelData and attachments properties:

channelData JSON schema for the Aura response semantic model v3

The root channelData properties are included in the JSON schema for channelData v3 response model
Root attachment properties

The fields included in the attachments property are defined in the section Root attachments properties
SkillPayload property

The fields included in the SkillPayload property are defined in the section SkillPayload property

Root attachments properties

Root attachments properties are an array of elements in the root of an activity that are intended to send specific responses from the skill to the channel. A single Aura response may contain different types of attachments. Find here more information regarding Direct Line attachment.

This field is kept as sent by the skill both by aura-groot and aura-bridge.

For third-party skills, the idea is to send here and attachment of contenType: application/json, although a devoted and specific contenType can be used, with the whole response of the skill to the user.

Root attachments properties are shown in the tables below. Mandatory sub-properties are highlighted in bold.

Properties	Type	Description
contentType	string	Different values depending on the attachment type. Check them in contentType section.
version	string	Version of the specification
content	content	Content of the attachment itself. See sub-properties in content properties section.
name	string	Descriptive name for the attachment

contentType properties

Attachment type	Values
Adaptive Cards	`application/vnd.microsoft.card.adaptive`
Hero Cards	`application/vnd.microsoft.card.hero`
JSON	`application/json`
ZIP	`application/zip`
Files sent from `aura-bot`	`application/vnd.telefonica.aura.file`
Templates sent from `aura-bot`	`application/vnd.telefonica.aura.template`
Suggestions v3 sent from `aura-bot`	`application/vnd.telefonica.aura.suggestion`

From the different types of attachments set above for the contentType property, the following table matches different Aura channels with the ones they support:

	Movistar Plus	STB	Movistar Home
Adaptive Cards	no	no	no
Hero Cards	no	no	no
customData (JSON / ZIP)	yes	yes	yes
customData (JSON-LA / ZIP)	no	no	yes

Adaptive card model

Adaptive Card is a customizable card that can contain any combination of text, speech, images, buttons and input fields. The standard version implemented is 1.5.

📄 Check the official website for Adaptive Cards.

An example of Adaptive Card format is shown below.

Hero card model

A Hero Card is a card that typically contains a single large image, one or more buttons and text.

An example of Hero Card format is shown below.

JSON response model

In this type of attachment, we only have three content properties:

type: type of JSON object. Currently, this field is only suitable for the actions specified in actions in channelData v3 although in further versions it can be implemented for other domains.
data: JSON data itself.
thirdParties: array of ThirdParty objects. This property includes information about the third-party or partner’s integrations that the channel should receive to correctly manage the request and the responses taking into account this partner. It follows the thirdParty type properties where the field data is an open object that depends on the specific third-party (See the thirdParty type properties in channeldata-3.0.0-response.schema.json. This value is optional.

This response is intended for responses from underlying APIs, where the channel will be in charge of rendering the response.

{
            "contentType": "application/json",
            "content": {
                "type": "",
                "data": {}
            },
            "name": "AuraCustomData"
        }

ZIP response model

In this case, the field content will include the ZIP file itself. This response is intended for responses which require downloading a file.

{
            "contentType": "application/zip",
            "content": "eJztnetu4sqWx18FWdqtGU0DLt/dUtSigfRmTkgygY66NdqKHKgk3m1stm3Snd3KI8yn8wTzAPNhNI/QLzaryjYYg4MNLsBpH22dcHHXf5Xrslb9KK/6wflPU8y940aO7WPbv7FMz+fecmPDN7h3PzgPW3fk74OL4S/34PvTd82m4/sjY/SAG2PnTmmMnElz4jzCPzTcqTXzmub0wbGx0AzL9JoeNtzRw/uJM8Ynj87YxX+almW8uTMtH7snHz7VW+
…
/dTpnei3d7XhaJabxyZtfninVQrIeKheBLSaUrtwW+1CQ5uaFSzOzm1z42u3RJhS/LGglWGyp/BdJSbaisWHYFmAsGzKXAl9lWqwyfAaf6sdcxdLnQ34wuSbh+fOSyYBZwsGfAiWlHQC1JXDE2fOPGGI9N0ux0qQgfGiM/iE373U6v1Rh0W1ft38NwaEZNGUHXgO8FelLXBHtecGDPYEYAqFcLalFz7mpX2IMo0KvVa7AUJQlxTPuOkNHn5+f/B5p62Oo=",
            "name": "AuraCustomData"
        }

Once the channel gets the ZIP file, it needs to be uncompressed. For example, for an Android application the process would be similar to the one below:

dataInflated = zlib.inflateSync(new Buffer(dataStringifiedAndDeflatedAndBase64, 'base64')).toString();

And for parsing:

object = JSON.parse(dataInflated);

For inflating and deflating in Android, you may use the classes called Inflater and Deflater.

Files sent from Aura Bot

A file is a special component that can be included in certain channels, such as WhatsApp. Constructors can configure a use case to send a file to the user by providing its URL. The file can be sent as a text message or as an attached file.

{
"contentType": "application/vnd.telefonica.aura.file",
"content": { "url": "https://link.com/file.pdf", "fileName": "file.pdf", "caption": "My file" }
}

Templates sent from Aura Bot

A template is defined as a combination of different elements (multimedia, buttons, different designs for texts, etc.) that can be used for sending proactive and enricher messages to the user in certain channels, such as WhatsApp. Constructors can configure a use case to send a template. Currently, templates can only be sent unidirectionally: from the channel to the user.

Suggestions v3 sent from Aura Bot

A suggestions v3 is defined to send as attachment with contentType: application/vnd.telefonica.aura.suggestion. Example:

   {
            contentType: AuraModels.AuraAttachmentContentType.AuraSuggestion,
            content: {
               suggestions
            }
   }

content properties

The properties of content type may include the following sub-properties in the table below. We have included just certain properties as they depend on the content type.

Property	Type	Description
type	string	For AdaptiveCard attachments: value: “AdaptiveCard”.
version	string	For AdaptiveCard attachments: version of the specification. For Aura internal attachments such as SingleActivity: version of the specification.
headerImage	string	For AdaptiveCard attachments: URL of the image in the header.
body	body	For AdaptiveCard attachments: body of the AdaptiveCards.
actions	action[]	For AdaptiveCard attachments: Actions available in the AdaptiveCard. They can be: action.OpenUrl, action.ShowCard, action.Submit
buttons	button[]	For HeroCard attachments: button that can be pressed by the user.
data	JSON object	For JSON attachments: JSON object.

SkillPayload property

This field includes parameters with information generated from the skill to aura-groot. It allows aura-groot to handle and log properly the activities.

It contains the following property:

Properties	Type	Description
intentResult	SkillPayloadIntentResult	Intent and entity definition

SkillPayloadIntentResult

intentResult contains the following sub-properties:

Properties	Type	Description
name	string	Unique identifier of the user’s intention. It should be a human-understandable but machine-readable string
entities	entities	Type and extract of the entity

Entities

entities contains the following sub-properties:

Properties	Type	Description
type	string	String with a unique name to identify the entity type (i.e., `ent.movie`)
entity	string	String with the extract of the utterance that is handled as an entity for the recognizer (“the lord of the rings”)

Check the associated fields in the examples below.

Response to send only a text

Activity to send only text

{
   "locale":"en-EN",
   "type":"message",
   "from":{
      "id":"user1"
   },
   "text":"Hi, how are you? Let me know how I can help you.",
   "speak":"Hi, how are you? Let me know how I can help you.""channelData":{
      "payload":{
         "auraGroot":{
            "channelConversationId":"<channelConversationId>",
            "channelId":"<channelId>",
            
         },
         "skill":{
            "intentResult":{
               "name":"intention-of-the-user",
               "entities":[
                  {
                     "type":"type-of-the-entity",
                     "entity":"part-of-the-utterance",
                     "the lord of the rings"")"
                  }
               ]
            }
         }
      },
      "version":"3",
      "correlator":"19d63cd4-8f7e-4194-837d-c55991b1afcd"
   }
}

Response to send more complex data

Activity with attachments

{
   "locale":"en-EN",
   "type":"message",
   "from":{
      "id":"user1"
   },
   "attachments":[
      {
         "contentType":"application/json",
         "content":{
            "The json response of your bot"
         }
      }
   ],
   "text":"Hi, how are you? Let me know how I can help you.",
   "speak":"Hi, how are you? Let me know how I can help you.""channelData":{
      "payload":"auraGroot":{
         "channelConversationId":"<channelConversationId>",
         "channelId":"<channelId>",
         
      },
      "skill":{
         "intentResult":{
            "name":"intention-of-the-user",
            "entities":[
               {
                  "type":"type-of-the-entity",
                  "entity":"part-of-the-utterance",
                  "the lord of the rings"")"
               }
            ]
         }
      }
   },
   "version":"3",
   "correlator":"19d63cd4-8f7e-4194-837d-c55991b1afcd"
}

Docs:

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

Actions in channelData v3

List of the actions returned by Aura with channelData model v3

Introduction

Actions are the way of translating the Aura’s answer into a direct operation from the channel, i.e., Aura informs the channel how to act depending on the user’s intention and the result provided by aura-bot.

The following sections show the details of the response custom data depending on the domain of the user’s intention. The columns of the tables describe the action name, channel reaction and description.

The value N/A is included in case of “not apply” (no action sent or no content attached).

Cross actions

These actions can be added to any use case. The specific values will depend on the use case being resolved. The expectation in these cases is that the channel understands these actions with their possible values so that, regardless of which use case the user has requested, if the channel receives an action (for example, MAKE_SOUND) it will be able to trigger it.

This means that, although in the following tables an N/A (Not Apply) appears in the “Actions” column, the channel could always receive one of the cross actions.

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
Make a sound	The use case result should be shown to the user with a positive sound	N/A	N/A	N/A	MAKE_SOUND	channel	{}	{sound}
Click a key remotely	Click a key remotely. The specific values of the keyCodes are defined above in each use case	N/A	N/A	N/A	SEND_KEY	stb	{}	{keyCode, deviceId, levels}
Redirect	Redirect command must send a message to the bot with the `auraCommand` sent in the action	REDIRECT.COMMAND	redirect	AuraCommand	N/A	channel	N/A	N/A

Examples are included in Cross action examples.

Small talk (a.k.a. common domain)

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
No reaction for Common. The channel shows what comes from Aura	Greet the user	COMMON.GREETINGS	N/A	N/A	N/A	N/A	N/A	N/A
No reaction for Common. The channel shows what comes from Aura	Say goodbye to the user	COMMON.GOODBYES	N/A	N/A	N/A	N/A	N/A	N/A
No reaction for Common. The channel shows what comes from Aura	Thank the user	COMMON.THANKYOUS	N/A	N/A	N/A	N/A	N/A	N/A
No reaction for Common. The channel shows what comes from Aura	The user is angry with Aura	COMMON.SWEARWORDS	N/A	N/A	N/A	N/A	N/A	N/A
No reaction for Common. The channel shows what comes from Aura	Initialize tv use cases	COMMON.INIT	N/A	N/A	N/A	N/A	N/A	N/A
The Help App is started	The user is asking for help	COMMON.HELP	N/A	N/A	N/A	N/A	N/A	N/A

Generic questions

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
No reaction for Generic. The channel shows what comes from Aura	The question of the user needs to be disambiguated	DISAMBIGUATION	N/A	The disambiguation information will be included in the corresponding attachment with the array of options to be shown to the user	N/A	N/A	N/A	N/A

Examples are included in Generic questions examples.

None

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
No reaction. The channel shows what comes from Aura	When handling an unsupported intent by the current channel	NONE	N/A	N/A	N/A	N/A	N/A	N/A

Video

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
No reaction. The channel shows what comes from Aura (only text and suggestions)	No content found. User wants to watch a channel on TV or a VOD content but it does not exist on catalog.	MEDIA.SEARCH	N/A	N/A	N/A	N/A	N/A	N/A
Show content details	User wants to watch content on TV. Content search with one result found.	MEDIA.SEARCH	details	Object Kernel result	N/A	N/A	N/A	N/A
Content list	User wants to watch content on TV. Content search with several results found.	MEDIA.SEARCH	content_list	Array of object Kernel result	N/A	N/A	N/A	N/A
Content list	User wants to search content in a third party platform (for example Netflix)	MEDIA.SEARCH	content_list	Array of object Kernel result	N/A	N/A	N/A	N/A
No reaction, the channel shows what comes from Aura. (Only text and suggestions)	Recommendation content to content with no contents found	MEDIA.RECOMMENDATION_C2C	N/A	N/A	N/A	N/A	N/A	N/A
No reaction. The channel shows what comes from Aura	Recommendation content to content with one content found	MEDIA.RECOMMENDATION_C2C	details	Object Kernel result	N/A	N/A	N/A	N/A
No reaction. The channel shows what comes from Aura	Recommendation content to content with contents found	MEDIA.RECOMMENDATION_C2C	content_list	Array of object Kernel result	N/A	N/A	N/A	N/A
No reaction. The channel shows what comes from Aura	Personalized recommendation with no content	MEDIA.RECOMMENDATION_C2P	N/A	N/A	N/A	N/A	N/A	N/A
No reaction. The channel shows what comes from Aura	Personalized recommendation with one content result	MEDIA.RECOMMENDATION_C2P	details	Object Kernel result	N/A	N/A	N/A	N/A
Content list	Content recommendation with results found. Similar to previous one but using the JSON coming from Kernel Recommendations API	MEDIA.RECOMMENDATION_C2P	content_list	Array of object Kernel result	N/A	N/A	N/A	N/A
Show content details	Get more details about the content displayed on the second device	MEDIA.SHEET_SECOND_SCREEN	details	Object Kernel result	N/A	N/A	N/A	N/A
Show content details	Get more details about the content displayed on TV	MEDIA.SHEET_TV	details	Object Kernel result	N/A	N/A	N/A	N/A
Show content details	User wants to play content, but it is not included in user’s subscription	CONTENT.PLAY	details	Object Kernel result	N/A	N/A	N/A	N/A
Show content details	User wants to watch a channel, but it is not included in user’s subscription	CHANNEL.PLAY	details	Object Kernel result	N/A	N/A	N/A	N/A
Play content	User wants to play a specific content	CONTENT.PLAY	details	Object Kernel result	REMOTEON.PLAYTO	stb	{}	{deviceId, contentId, catalogType}
Play the content on focus	Watch this VOD content	CONTENT.PLAY	details	Object Kernel result	REMOTEON.PLAYTO	stb	{}	{deviceId, contentId, liveProgramId,catalogType, resumeTime}
Tune to channel	User wants to tune a specific channel	CHANNEL.PLAY	details	Object Kernel result	REMOTEON.ZAPTO	stb	{}	{deviceId, channeId, channelNumber}
Play the channel on focus	Watch this channel	CHANNEL.PLAY	details	Object Kernel result	REMOTEON.ZAPTO	stb	{}	{deviceId, channeId, channelNumber}
React to received Key	Watch from the beginning	FROM_BEGINNING	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
React to received Key	Record content	REC	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
React to received Key	User wants to play a third-party content	PLAY	details	Object Kernel result	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Change play parameter	Turn English audio and turn English subtitles on / Play in original version for a VOD content	CONTENT.CONFIG_AUDIO_SUBTITLES	N/A	N/A	REMOTEON.PLAYPARAMS	stb	{}	{deviceId, contentId, liveProgramId,catalogType, audio, subtitles}
Change play parameter	Turn English audio and turn English subtitles on / Play in original version for a channel	CHANNEL.CONFIG_AUDIO_SUBTITLES	N/A	N/A	REMOTEON.LIVEPARAMS	stb	{}	{deviceId, channeId, channelNumber, audio, subtitles}
Change play parameter	Turn English audio on / Play in original version for a VOD content	CONTENT.CONFIG_AUDIO	N/A	N/A	REMOTEON.PLAYPARAMS	stb	{}	{deviceId, contentId, liveProgramId,catalogType, audio}
Change play parameter	Turn English audio on / Play in original version for a channel	CHANNEL.CONFIG_AUDIO	N/A	N/A	REMOTEON.LIVEPARAMS	stb	{}	{deviceId, channeId, channelNumber, audio}
Change play parameter	Turn English subtitles on / Play in original version for a VOD content	CONTENT.CONFIG_SUBTITLES	N/A	N/A	REMOTEON.PLAYPARAMS	stb	{}	{deviceId, contentId, liveProgramId,catalogType, subtitles}
Change play parameter	Turn english subtitles on / Play in original version for a channel	CHANNEL.CONFIG_SUBTITLES	N/A	N/A	REMOTEON.LIVEPARAMS	stb	{}	{deviceId, channeId, channelNumber, subtitles}
Change play parameter	Turn off subtitles for a VOD content	CONTENT.DEACTIVATE_SUBTITLES	N/A	N/A	REMOTEON.PLAYPARAMS	stb	{}	{deviceId, contentId, liveProgramId,catalogType, subtitles}
Change play parameter	Turn off subtitles for a channel	CHANNEL.DEACTIVATE_SUBTITLES	N/A	N/A	REMOTEON.LIVEPARAMS	stb	{}	{deviceId, channeId, channelNumber, subtitles}
Move channels down	Move channels down	CHANNEL_DOWN	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Move channels up	Move channels up	CHANNEL_UP	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Mute TV	Mute TV	MUTE	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Unmute TV	Unmute TV	UNMUTE	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Switch TV off	Switch TV off	SWITCH_OFF	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Switch TV on	Switch TV on	SWITCH_ON	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Pause TV	Pause the current program being played	PAUSE	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Resume TV	Resume TV	RESUME	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Stop TV	Stop TV	STOP	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Volume up TV	Volume up	VOLUME_UP	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Volume down TV	Volume down	VOLUME_DOWN	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Move forward	Move forward	MOVE_FORWARD	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Move back	Move back	MOVE_BACK	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId, levels}
Disable subtitles	Disable subtitles	REMOTEON_AUDIO_SUBTITLES	N/A	N/A	REMOTEON.AUDIO_SUBTITLES	stb	{}	{keycode, deviceId, subtitles}
Change language	Change language	REMOTEON_AUDIO_SUBTITLES	N/A	N/A	REMOTEON.AUDIO_SUBTITLES	stb	{}	{keycode, deviceId}
Go to app	Navigate/open a section from a third party	GOTOAPP	N/A	N/A	GOTOAPP	stb	{}	{name, id, deviceId}

Examples are included in Video examples and can be easily accessed following the hyperlink defined in Actions Name column.

Communications

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
Call to the number the user sends afterwards	Make a phone call	COMMUNICATIONS.CALL	N/A	N/A	COMMUNICATIONS.CALL	channel	{}	{}
Call to the number sent by the user	Make a phone call to the given phone number	COMMUNICATIONS.CALL_NUMBER	N/A	N/A	COMMUNICATIONS.CALL_NUMBER	channel	{}	{items:[]}
Call to the contact name sent by the user	Make a phone call to the given contact name	COMMUNICATIONS.CALL_NAME	N/A	N/A	COMMUNICATIONS.CALL_NAME	channel	{}	{items: []}
Sent a voice mail	Sent a voice mail to the given contact	COMMUNICATIONS.VOICE_MAIL_CALL	N/A	N/A	COMMUNICATIONS.VOICE_MAIL_CALL	channel	{}	{}
Check incoming and outgoing calls	Check calls	COMMUNICATIONS.CHECK_ALL_CALLS	N/A	N/A	COMMUNICATIONS.CHECK_ALL_CALLS	channel	{}	{}
Ignore incoming call	Mute the incoming call	COMMUNICATIONS.IGNORE_INCOMING_CALL	N/A	N/A	COMMUNICATIONS.IGNORE_INCOMING_CALL	channel	{}	{}
Pick up incoming call	Pick up incoming call	COMMUNICATIONS.PICKUP	N/A	N/A	COMMUNICATIONS.PICKUP	channel	{}	{}
Redial last outgoing number	Redial a number	COMMUNICATIONS.REDIAL	N/A	N/A	COMMUNICATIONS.REDIAL	channel	{}	{} or 0
Add contact to address book	Add contact to address book	CONFIG.ADD_CONTACT	N/A	N/A	CONFIG.ADD_CONTACT	channel	{}	{}
Disable silent mode	Unmute the device	CONFIG.SILENT_MODE_OFF	N/A	N/A	CONFIG.SILENT_MODE_OFF	channel	{}	{}
Enable silent mode	Mute the device	CONFIG.SILENT_MODE_ON	N/A	N/A	CONFIG.SILENT_MODE_ON	channel	{}	{}

Examples are included in Communication actions examples.

Domotics

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
Switch off the lights	Switch off the lights	DOMOTICS.LIGHT_OFF	N/A	N/A	DOMOTICS.LIGHT_OFF	channel	{}	{actionCode, deviceId, levels}
Switch on the lights	Switch on the lights	DOMOTICS.LIGHT_ON	N/A	N/A	DOMOTICS.LIGHT_ON	channel	{}	{actionCode, deviceId, levels}

Examples for each action are included in Domotics actions examples.

e-commerce

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
Add item to wish list	Add item to wish list	ECOMMERCE.ADD_TO_WISH_LIST	N/A	N/A	ECOMMERCE.ADD_TO_WISH_LIST	channel	{}	{}

Miscellaneous

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
Turn the radio off	Turn the radio off	RADIO.OFF	N/A	N/A	RADIO.OFF	channel	{}	{}
Listen to the radio	Turn the radio on with a specific station	RADIO.LISTEN	N/A	N/A	RADIO.LISTEN	channel	{}	{stationId, stationName, stationText}
Listen to a podcast	Listen to a podcast	PODCAST.LISTEN	N/A	N/A	PODCAST.LISTEN	channel	{}	{podcastName}

Check time	What time is it	MISCELLANEOUS.TIME_CHECK	N/A	N/A	MISCELLANEOUS.TIME_CHECK	channel	{}	{}
Provide weather forecast	Weather forecast	MISCELLANEOUS.WEATHER	N/A	N/A	MISCELLANEOUS.WEATHER	channel	{}	{}
Start playing news	Listen to news	MISCELLANEOUS.NEWS_LISTEN	N/A	N/A	MISCELLANEOUS.NEWS_LISTEN	channel	{}	{}
Show wifi connection data	Retrieve wifi connection data	WIFI.GET_ACCESS	wifi_info	{status, ssid, password, bssid, channel, authentication}	N/A	N/A	N/A	N/A

Examples are included in Miscellaneous actions examples.

Channel reaction	Description	Intent result name	Content type	Content data	Actions name	Actions target	Actions postback	Actions params
Go to the selected section	Show the selected section	NAVIGATION.SECTION_SHOW	N/A	N/A	NAVIGATION.SECTION_SHOW	stb	{}	{name, id, deviceId}
Like the back button was pressed by the user	Go to previous page	NAVIGATION.BACK	N/A	N/A	SEND_KEY	stb	{}	{keycode, deviceId}
Go to next item in the given carousel or list	Go to next item in carousel	MEDIA.CAROUSEL_NEXT	N/A	N/A	MEDIA.CAROUSEL_NEXT	channel	{}	{}
Go to previous item in the given carousel or list	Go to previous item in carousel	MEDIA.CAROUSEL_PREVIOUS	N/A	N/A	MEDIA.CAROUSEL_PREVIOUS	channel	{}	{}

Examples are included in Navigation actions examples.

Actions examples

Cross action examples

Make sound

"channelData": {
                    "intentResult": {
                         "name": "COMMON.GREETINGS"
                    },
                    "actions": [{
                       "name": "MAKE_SOUND",
                       "target": "channel",
                       "params": {
                            "sound": "positive"
                        }
                    }],
}

Send remote key

"channelData": {
                    "intentResult":{
                         "name": "NAVIGATION.BACK"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "BACK",
                            "devideId": "Mi-29283"
                        }
                    }],

Redirect command

"customData": {
                    "type": 'redirect',
                    "action": 'REDIRECT.COMMAND',
                    "data": {
                        "auraCommand": {
                            "type": "suggestion",
                            "value": {
                                "intent": "intent.common.greetings"
                            }
                        }
                    }
                }

In this example, if aura-bridge receives this message, it must send an auraCommand with the intent intent.common.greetings to the bot.

Generic questions examples

"content": {
                        "data": {
                            "question": "¿Dónde puedo comprar un móvil?"
                        }
                    }

Video examples

Search content in a third-party platform

Access here to comprehensive information regarding Kernel definitions

"channelData": {
  "intentResult": {
    "name": "MEDIA.SEARCH",
    "entities": []
  },
  "actions": []
}
"attachments": [
  {
    "content": {
      "type": "content_list",
      "data": [
        {<JSON response from the **Kernel** search API>
        }
      ],
      "thirdParties ": [
        {
          "name": "netflix",
          "data": {<headers response from the **Kernel** search API (To be defined by **Kernel** team)>
          }
        }
      ]
    }
  }
]

Play content

"channelData": {
                "intentResult":{
                    "name": "CONTENT.PLAY"
                },
                "actions": [
                    {
                        "name": "REMOTEON.PLAYTO",
                        "target": "stb",
                        "params": {
                             "catalogType": "vod",
                             "contentId": "12345",
                             "deviceId": "Mi-29283"
                        }
                    }
]}

Play content on focus

"channelData": {
                "intentResult":{
                    "name": "CONTENT.PLAY"
                },
                "actions": [
                    {
                        "name": "REMOTEON.PLAYTO",
                        "target": "stb",
                        "params": {
                             "catalogType": "l7d",
                             "contentId": "12345",
                             "liveProgramId": "54321",
                             "resumeTime": 24,
                             "deviceId": "Mi-29283"
                        }
                    }
]}

Play channel

"channelData": {
                "intentResult":{
                    "name": "CHANNEL.PLAY"
                },
                "actions": [
                    {
                        "name": "REMOTEON.ZAPTO",
                        "target": "stb",
                        "params": {
                             "channelNumber": 1,
                             "channelId ": "123",
                             "deviceId": "Mi-29283"
                        }
                    }

From beginning

"channelData": {
                "intentResult":{
                    "name": "FROM_BEGINNING"
                },
                "actions": [
                    {
                        "name": "SEND_KEY",
                        "target": "stb",
                        "params": {
                             "keyCode": "REDO",
                             "deviceId": "Mi-29283"
                        }
                    }

Recording

"channelData": {
                "intentResult":{
                    "name": "REC"
                },
                "actions": [
                    {
                        "name": "SEND_KEY",
                        "target": "stb",
                        "params": {
                             "keyCode": "REC",
                             "deviceId": "Mi-29283"
                        }
                    }

Play a third-party content of focus

"channelData": {
                "intentResult":{
                    "name": "PLAY"
                },
                "actions": [
                    {
                        "name": "SEND_KEY",
                        "target": "stb",
                        "params": {
                             "keyCode": "PLAY",
                             "deviceId": "Mi-29283"
                        }
                    }

Change audio and subtitles parameter for VOD content

"channelData": {
                "intentResult":{
                    "name": "CONTENT.CONFIG_AUDIO_SUBTITLES"
                },
                "actions": [
                    {
                        "name": "REMOTEON.PLAYPARAMS",
                        "target": "stb",
                        "params": {
                             "catalogType": "l7d",
                             "contentId": "12345",
                             "liveProgramId": "54321",
                             "deviceId": "Mi-29283",
                             "audio": "eng",
                             "subtitles": "eng"
                        }
                    }

Change audio and subtitles for a channel

"channelData": {
                "intentResult":{
                    "name": "CHANNEL.CONFIG_AUDIO_SUBTITLES"
                },
                "actions": [
                    {
                        "name": "REMOTEON.LIVEPARAMS",
                        "target": "stb",
                        "params": {
                             "channelNumber": 1,
                             "channelId ": "123",
                             "deviceId": "Mi-29283",
                             "audio": "eng",
                             "subtitles": "eng"
                        }
                    }

Change audio parameter for VOD content

"channelData": {
                "intentResult":{
                    "name": "CONTENT.CONFIG_AUDIO"
                },
                "actions": [
                    {
                        "name": "REMOTEON.PLAYPARAMS",
                        "target": "stb",
                        "params": {
                             "catalogType": "l7d",
                             "contentId": "12345",
                             "liveProgramId": "54321",
                             "deviceId": "Mi-29283",
                             "audio": "eng"
                        }

Change audio parameter for channel

"channelData": {
                "intentResult":{
                    "name": "CHANNEL.CONFIG_AUDIO"
                },
                "actions": [
                    {
                        "name": "REMOTEON.LIVEPARAMS",
                        "target": "stb",
                        "params": {
                             "channelNumber": 1,
                             "channelId ": "123",
                             "deviceId": "Mi-29283",
                             "audio": "eng"
                        }
                    }

Change subtitles parameter for VOD content

"channelData": {
                "intentResult":{
                    "name": "CONTENT.CONFIG_SUBTITLES"
                },
                "actions": [
                    {
                        "name": "REMOTEON.PLAYPARAMS",
                        "target": "stb",
                        "params": {
                             "catalogType": "l7d",
                             "contentId": "12345",
                             "liveProgramId": "54321",
                             "deviceId": "Mi-29283",
                             "subtitles": "eng"
                        }
                    }

Change subtitles parameter for channel

"channelData": {
                "intentResult":{
                    "name": "CHANNEL.CONFIG_SUBTITLES"
                },
                "actions": [
                    {
                        "name": "REMOTEON.LIVEPARAMS",
                        "target": "stb",
                        "params": {
                             "channelNumber": 1,
                             "channelId ": "123",
                             "deviceId": "Mi-29283",
                             "subtitles": "eng"
                        }
                    }

Deactivate subtitles parameter for VOD content

"channelData": {
                "intentResult":{
                    "name": "CONTENT.DEACTIVATE_SUBTITLES"
                },
                "actions": [
                    {
                        "name": "REMOTEON.PLAYPARAMS",
                        "target": "stb",
                        "params": {
                             "catalogType": "l7d",
                             "contentId": "12345",
                             "liveProgramId": "54321",
                             "deviceId": "Mi-29283",
                             "subtitles": "void"
                        }
                    }

Deactivate subtitles parameter for channel

"channelData": {
                "intentResult":{
                    "name": "CHANNEL.DEACTIVATE_SUBTITLES"
                },
                "actions": [
                    {
                        "name": "REMOTEON.LIVEPARAMS",
                        "target": "stb",
                        "params": {
                             "channelNumber": 1,
                             "channelId ": "123",
                             "deviceId": "Mi-29283",
                             "subtitles": "void"
                        }
                    }

Move channels down

"channelData": {
                    "intentResult": {
                         "name": "CHANNEL_DOWN"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "P-",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "1"
                        }
                    }],
}

Move channels up

"channelData": {
                    "intentResult": {
                         "name": "CHANNEL_UP"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "P+",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "1"
                        }
                    }],
}

Mute TV

"channelData": {
                    "intentResult": {
                         "name": "MUTE"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "MUTE",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA"
                        }
                    }],
}

Unmute TV

"channelData": {
                    "intentResult": {
                         "name": "UNMUTE"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "UNMUTE",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA"
                        }
                    }],
}

Switch TV off

"channelData": {
                    "intentResult": {
                         "name": "SWITCH_OFF"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "STANDBY",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA"
                        }
                    }],
}

Switch TV on

"channelData": {
                    "intentResult": {
                         "name": "SWITCH_ON"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "STANDBY",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "1"
                        }
                    }],
}

Pause TV

"channelData": {
                    "intentResult": {
                         "name": "PAUSE"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "PAUSE",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA"
                        }
                    }],
}

Resume TV example

"channelData": {
                    "intentResult": {
                         "name": "RESUME"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "PLAY",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        }
                    }],
}

Stop TV

"channelData": {
                    "intentResult": {
                         "name": "STOP"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "STOP",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA"
                        }
                    }],
}

Volume up

"channelData": {
                    "intentResult": {
                         "name": "VOLUME_UP"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "VOL+",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "5"
                        }
                    }],
}

Volume down

"channelData": {
                    "intentResult": {
                         "name": "VOLUME_DOWN"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "VOL-",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "5"
                        }
                    }],
}

Move forward

"channelData": {
                    "intentResult": {
                         "name": "MOVE_FORWARD"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "MOVE_FORWARD",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "60"
                        }
                    }],

Move back

"channelData": {
                    "intentResult": {
                         "name": "MOVE_BACK"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "MOVE_BACK",
                        	"deviceId": "10.149.202.30_E0B70ADBE4CA",
                        	"levels": "60"
                        }
                    }],

Disable subtitles

"channelData": {
                "intentResult": {
                    "name": "AUDIO_SUBTITLES",
                    "entities": []
                },
                "actions": [
                    {
                        "name": "AUDIO_SUBTITLES",
                        "target": "stb",
                        "params": {
                            "deviceId": "Mi-29283",
                            "subtitles": "None"
                        }
                    },
                    {
                        "name": "MAKE_SOUND",
                        "target": "channel",
                        "params": {
                            "sound": "positive"
                        }
                    }
                ],

Change language

"channelData": {
                "intentResult": {
                    "name": "AUDIO_SUBTITLES",
                    "entities": []
                },
                "actions": [
                    {
                        "name": "REMOTEON.AUDIO_SUBTITLES",
                        "target": "stb",
                        "params": {
                            "deviceId": "Mi-29283"
                        }
                    },
                    {
                        "name": "MAKE_SOUND",
                        "target": "channel",
                        "params": {
                            "sound": "positive"
                        }
                    }
                ],

Go to app

"channelData": {
                "correlator": "520f1e3a-f02b-4bf1-bcda-19d30e0cba0b",
                "version": "3",
                "intentResult": {
                    "name": "GOTOAPP",
                    "entities": [{
                        "type": "ent.tv_app",
                        "entity": "Netflix",     
                    }]
                },
                "actions": [
                    {
                        "name": "GOTOAPP",
                        "target": "stb",
                        "params": {
                            "deviceId": "Mi-29283",
                            "name": "Netflix",
                            "id": "ID03242"
                        }
                    },
                    {
                        "name": "MAKE_SOUND",
                        "target": "channel",
                        "params": {
                            "sound": "positive"
                        }
                    }
                ],
                "status": {
                    "code": "SUCCESS",
                    "message": "Success"
                }
            }

Communications examples

Call a number

"channelData": {
                    "actions": [{
                       "name": "COMMUNICATIONS.CALL_NUMBER",
                       "target": "channel",
                       "params": {
                            "items": [{
                                "type": "ent.phonenumber",
                                "value": "916547889"
                            }]
                        }],

Call a contact

"channelData": {
                    "actions": [{
                       "name": "COMMUNICATIONS.CALL_NAME",
                       "target": "channel",
                       "params": {
                            "items": [{
                                "type": "ent.com_name",
                                "value": "mamá"
                            }]
                        }],

Redial a number

"channelData": {
                    "actions": [{
                       "name": " COMMUNICATIONS.REDIAL",
                       "target": "channel",
                       "params": {
                            "items": [{
                                "type": "ent.phonenumber",
                                "value": "916547889"
                            }]
                        }],

Domotics examples

Switch off the lights

"channelData": {
                    "actions": [{
                       "name": "DOMOTICS.LIGHT_OFF",
                       "target": "channel",
                       "params": {
                            "actionCode": "LIGHT_OFF",
                            "deviceId": "",
                            "levels": "1"
                        }
                    }],

Switch on the lights

"channelData": {
                    "actions": [{
                       "name": "DOMOTICS.LIGHT_ON",
                       "target": "channel",
                       "params": {
                            "actionCode": "LIGHT_ON",
                            "deviceId": "",
                            "levels": "1"
                        }
                    }],

Miscellaneous examples

Get access to wifi

 "content": {
      "type": "wifi_info",
      "data": {
         "status": "ok",
         "ssid": "xxxx",
         "password": "yyyy",
         "bssid": "zzzzzz",
         "channel": "10",
         "authentication": "WPA-2",
      }
}

Show selected section

"channelData": {
                    "actions": [
                        {
                            "name": "NAVIGATION.SECTION_SHOW",
                            "target": "stb",
                            "params": {
                                "deviceId": "Mi-29283",
                                "name": "Seccion1",
                                "id": "ID0666"
                            }
                        },
                        {
                            "name": "MAKE_SOUND",
                            "target": "channel",
                            "params": {
                                "sound": "positive"
                            }
                        }
                    ]
}

"channelData": {
                    "intentResult":{
                         "name": "NAVIGATION.BACK"
                    },
                    "actions": [{
                       "name": "SEND_KEY",
                       "target": "stb",
                       "params": {
                            "keyCode": "BACK",
                            "devideId": "Mi-29283
                        }
                    }],

Constants values

This section includes the possible values that some fields could take. Specifically, the fields defined here are activeApp from the request, target from the actions and sound from the cross action MAKE_SOUND defined in Aura’s response.

Active app values

App Name	Description
movistar	Telefonica TV platform. By default, application.
netflix	Netflix TV platform.

Action target values

Target Name	Description
channel	The action must be executed by the channel sending the request.
stb	The action must be executed over the Set-Top-Box.

Sound values

Sound	Description
positive	The channel might make a positive sound.
negative	The channel might make a negative sound.

Input examples

The information included in this section represents a subset of an example of third-party request. Concretely, a request that a user makes to Aura from Netflix app and with the needed permissions to ask for Netflix content.

"channelData": {
                "appContext": {
                    "application": {
                        "activeApp": "netflix",
                        "thirdParties": [
                                 "name": "netflix",
                                 "data": {
                                      "third_deviceID": "ESN Value",
                                      "persoParameters": {
                                                "cookieList": [ {
                                                          "name": "ABCDEG",
                                                          "value": "XXXX"
                                                          },
                                                          {
                                                          "name": "nfvdid",
                                                          "value": "YYYYY"
                                                          }],
                                                 "tokenDET": "Recommendation Token",
                                                 "vdid": "VDID Value"
                                       }
                                   }]
                     }
                 }
           }

Docs:

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

Aura channel model

The Aura channel model includes all the properties required for channels to communicate with Aura

Introduction

When integrating a channel into Aura, there are various properties, both mandatory and optional, that must be defined for the registration of this channel and in order to set its operational configuration within Aura.

In this framework, two scenarios arise, depending on the type of skill:

Registration of a channel that works against aura-bot skill
The tables below include the properties definition for this scenario
Registration of a channel that works against a third-party skill
This scenario includes certain particularities which are specifically described in the affected properties and marked as:

The tables that define Aura channel model includes the property type and a brief description of each of them, together with a column indicating which are the Aura Platform components affected by this property.

Properties marked in bold are mandatory.
Properties marked in italics are optional.
Values of Applicable Aura Platform components column:
- aura-configuration-api is not included, because it handles the configuration, so it uses everything.
- aura-bridge means aura-bridge and aura-bridge-outbound.

Channel configuration

Property	Type	Description	Applicable Aura Platform components
name	string	Descriptive name of the channel. Lowercase hyphen-separated words	All Aura components
prefix	string	Minimal expression of channel name. Lowercase hyphen-separated words	All Aura components
id	UUID	UUID that uniquely identifies the channel in Aura	All Aura components
brand	string	Identifier of the Telefónica brand this channel belongs to. It must be one of the brands defined in Kernel `D_Gbl_Brand` global dimension entity.	All Aura components
contact	string	Identifier of the type of contact channel. It must be one of the contact channels defined in Kernel `D_Gbl_Contact_Channel` global dimension entity.	All Aura components
dialogLibraries	array	Array of `dialogLibrary` model with all the use cases supported by the channel. Check the complete dialogLibrary model	aura-bot
actions	object	List of configurations for the different actions sent by aura-bot. Check the complete actions model	aura-bot
rcs	object	RCS configuration. Type `RCS model`. Check the complete RCS model	aura-bridge
requestOptions	object	Object with request options. Type `request model`. Check the complete requestOptions model	aura-groot, aura-bot, aura-bridge, aura-file-manager
responseOptions	object	Object of `response model` that describes all the options of the response to the channel. Check the complete responseOptions model	aura-groot, aura-bot, aura-bridge, aura-file-manager
security	object	Authentication options object type `security model`. Check the complete security model	aura-bot, aura-bridge, aura-file-manager, aura-authentication-api
whatsapp	object	Object of `whatsApp model` that describes all the WhatsApp channel options. Check the complete WhatsApp model	aura-groot, aura-bot
auraBotCacheTTL	number	Set custom cache lifetime in MongoDB by channel	aura-bot, aura-groot
type	string	Channel type: `whatsapp`, `auraline`, `rcs`. Used by aura-bridge to determine the correct plugin to handle incoming bot responses	aura-bridge
atria	object	Object of `Atria model` with application and preset configs by intent. Check the complete Atria model	aura-groot, aura-bot

1.1. NLP model

Channels working against a third-party skill: non-applicable model

Property	Type	Description	Applicable Aura Platform components
enabled	boolean	It indicates whether or not the channel counts on any training handled by aura-nlp. If not present, it means that no training has been provided for the channel	aura-bot, aura-nlp
stages	array	List of nlp stages configured. This field should NOT be configured. Is automatically filled by `aura-config-provision` job.	aura-kpis-uploader, nlp-provisioning

Channels working against a third-party skill: non-applicable model

Property	Type	Description	Applicable Aura Platform components

2.1. dialogLibrary model

Property	Type	Description	Applicable Aura Platform components
name	string	Unique name of the library	aura-bot
dialogs	array	Array of the `dialog` model, with all the dialogs supported by this library	aura-bot
authorization	`authorizationConfiguration` model	Authorization scopes and purposes	aura-bot

2.1.1. dialog model

Property	Type	Description	Applicable Aura Platform components
id	string	Unique identifier of the dialog. Usually a descriptive name	aura-bot
prefix	string	Unique identifier with the acronym of the dialog	aura-bot
triggerConditions	array	Array of `triggerCondition` model, with all the triggers leading to this dialog	aura-bot
channelDataVersion	string	`channelData` version	aura-bot
suggestions	boolean	Boolean value that indicates if the dialog should show suggestions	aura-bot
allowAnonymous	boolean	Boolean value that indicates if the dialog allows anonymous users	aura-bot
authorization	object	Array of the `authorizationConfiguration` model	aura-bot
bypass	object	`bypass` model	aura-bot

2.1.1.1. triggerCondition model

Property	Type	Description	Applicable Aura Platform components
id	string	Unique identifier of the intent. It should follow this format `intent.[case].[specific_resolution]`	aura-bot
contextFilters	array	Array of `contextFilter` model, with all the filters based on the user context that will control how the dialog is executed	aura-bot
entity	string	Canonical value of the entity, when needed to fill the intent resolution	aura-bot
settings	intentSettings	Intent properties which can be used to customize trigger conditions	aura-bot

2.1.1.1.1. contextFilter model

Property	Type	Description	Applicable Aura Platform components
name	string	Descriptive name of the filter	aura-bot
type	string	Descriptive name of the filter type	aura-bot
conditions	string	Boolean condition in spleen format that will control how the filter is validated. For instance: `/authData/subscriptionType neq 'postpaid'` will be truly if the `UserType` of the logged user is not `postpaid`	aura-bot
true-false	object	`conditionValidation` model that describes the behavior of the dialog under each result	aura-bot

2.1.1.1.1.1. conditionValidation model

Property	Type	Description	Applicable Aura Platform components
name	string	Descriptive name of the condition validation	aura-bot
breakDialogExecution	boolean	`true` if the dialog execution should be stopped	aura-bot
breakFilterEval	boolean	`true` if the filters validation should be stopped if this validation is successful	aura-bot
resource	string	Reference of the copy to be returned to the user if this validation is successful	aura-bot
suggestions	string	Flag to indicate whether or not the dialog should show suggestions if `contextFilter` is `true`	aura-bot
redirectToIntent	string	New intent to redirect	aura-bot
originalIntent	string	Original intent when context filter be applied	aura-bot

2.1.1.1.2. intentSettings model

Property	Type	Description	Applicable Aura Platform components
type	string	intentSettings type	aura-bot
action	string	Action to be performed and attached to the output message used in different channels	aura-bot
actions	actionConfig	V3 Actions to be performed and attached to the output message used in different channels	aura-bot
locales	intentSettingsLocales	Success or error messages to be displayed in output message	aura-bot
payload	object	Parameters needed to recreate output message	aura-bot
addEntitiesToPayload	boolean	Flag to indicate whether or not entities must be applied to the payload	aura-bot
needPlayingContent	boolean	Flag to indicate whether or not playingContent is needed	aura-bot
sound	Sound	Configuration involving sounds reproduced in different channels. Available values are defined in Sound enum.	aura-bot
swapEntityCanonValue	string	Array of entity’s types which will be swapped payload entity value from entity.entity to entity.canon	aura-bot
indexedResourceBase	string	POEditor resource reference to obtain deterministic value. e.g. `generic:faq-answer.`	aura-bot
addEntitiesToPayload	boolean	Flag to indicate whether or not entities must be applied to the payload.	aura-bot
confirmSuggestion	boolean	Flag to indicate whether or not suggestions must be confirmed.	aura-bot
resolutionIntent	string	Intent returned by `movistarResolution` API.	aura-bot
resolutionEntities	Entity[]	Entities returned by movistarResolution.	aura-bot
payloadType	payloadType	Payload type included in payloadType enum such as ‘radio’.	aura-bot
isFullscreen	boolean	Flag to indicate fullScreen behavior.	aura-bot
functions	functionsConfig	Parameters related to the configuration of functions	aura-bot
suggestions	boolean	Flag to indicate if suggestions will be returned	aura-bot

2.1.1.1.2.1. actionConfig model

Property	Type	Description	Applicable Aura Platform components
name	string	Action name	aura-bot
target	string	Action target	aura-bot
params	object	Action params	aura-bot
postBack	object	Action postBack	aura-bot

2.1.1.1.2.2. intentSettingsLocales model

Property	Type	Description	Applicable Aura Platform components
success	string	Success message array	aura-bot
error	string	Error message array	aura-bot

2.1.1.1.2.3. functionsConfig model

Property	Type	Description	Applicable Aura Platform components
params	string[]	Function params	aura-bot
algorithm	string	Function algorithm name or js plain code	aura-bot

2.1.1.2. bypass model

Property	Type	Description	Applicable Aura Platform components
duration	string	Time in minutes during which the bypass is valid. The dialog must provide a way of setting a default duration that will depend on the use case	aura-bot
payloadName	boolean	`true` if the dialog execution should be stopped	aura-bot
initialData	object	Initial data to store in the bypass. `Bypass.data`	aura-bot
recognizersEnabled	boolean	Enable recognizers when bypass is active	aura-bot
recognizersBreakIntents	string	Break intents to replace dialog	aura-bot

2.1.2. authorizationConfiguration model

Property	Type	Description	Applicable Aura Platform components
scopes	string	Scopes defined in Kernel	aura-bot
purposes	string	Purposes defined in Kernel	aura-bot

4.1. actions model

Property	Type	Description	Applicable Aura Platform components
afterLogin	actionAfterLogin	Configuration for action sent after login in WhatsApp	aura-bot
thirdPartyApp	actionThirdParty	Configuration for action to launch 3PA from dialog	aura-bot

4.1.1. actionAfterLogin model

Property	Type	Description	Applicable Aura Platform components
action	string	Action sent in `channelData`	aura-bot
type	string	Type sent in `channelData`	aura-bot
data	object	Data sent in `channelData`. It can contain the field `originalIntent`	aura-bot

4.1.2. actionThirdParty model

Property	Type	Description	Applicable Aura Platform components
action	string	Action sent in `channelData`	aura-bot
type	string	Type sent in `channelData`	aura-bot
data	object	Data sent in `channelData`	aura-bot
contentType	string	ContentType of the data in `channelData`	aura-bot

5.1. RCS model

Property	Type	Description	Applicable Aura Platform components
agentId	string	RCS agent ID	aura-bridge
clientToken	string	Token configured in RCS webhook	aura-bridge
email	string	RCS account email	aura-bridge
privateKey	string	RCS account private key in base64 format	aura-bridge

6.1. requestOptions model

Property	Type	Description	Applicable Aura Platform components
fileAttachments	fileAttachmentsModel	Set of settings needed to processing file attachments	aura-bot, aura-file-manager
requestOptionsVersion	any	Set of settings depending on the version	aura-bot, aura-bridge, aura-file-manager
defaultIntentByAttachment	any	Key value pairs with types of attachments and the intent to route these messages	aura-bot

6.1.1. fileAttachments model

Property	Type	Description	Applicable Aura Platform components
enabled	boolean	Enable/disable file attachment processing	aura-bot, aura-file-manager
enabledExtensions	string	Array with accepted file extensions (if not present, then all default files are accepted)	aura-file-manager
customProactiveDialogId	string	Dialog identifier that allows to substitute core unexpected-file dialog	aura-bot
validation	validation	Set of validations to apply to a file attachment	aura-file-manager

6.1.1.1. validation model

Validation is an object where keys are file extensions and values are objects with validations to apply to that particular file extension. The current available validations are related to size.

Property	Type	Description	Applicable Aura Platform components
size	Size	Size validation params	aura-file-manager

6.1.1.1.1. size

Property	Type	Description	Applicable Aura Platform components
max	number	Maximum size accepted	aura-file-manager
min	number	Minimum size accepted	aura-file-manager

7.1. responseOptions model

Property	Type	Description	Applicable Aura Platform components
dialogContext	dialogContext model	DialogContext configuration	aura-bot
versions	responseOptionsVersion	Response mode to be used by version (batch messages or single messages)	aura-bot, aura-bridge
needsEmptyResponseEvent	boolean	If `true`, the bot will respond with an event if no response is sent to an input message	aura-bridge
outputMessageFormat	string	Type of message supported by the channel. Possible values: - `custom`: use for TV channels. Recommended value in new channels - `enrich`: use for channels supporting Adaptive Cards (Novum) - `simple`: use for channels supporting Hero Cards (WhatsApp) Channels working against a third-party skill: `custom`	aura-bot
sendSpeak	boolean	Flag to indicate that this channel returns speak with all messages	aura-bot
disambiguationFormat	string	Format of disambiguation supported by the channel. Possible values: `suggestions`, `prompt`, `disabled`. By default, `prompt`	aura-bot
textConvert	boolean	It indicates whether the texts of each of the messages received must be converted to the WhatsApp markdown format. By default: `true`	aura-bridge
callbackOptions	callbackOptions	Parameter that defines URL and headers for Auraline callback	aura-bridge
suggestionsNumber	number	It indicates the number of suggestions to be returned in a message. Only applies to channelData v3.	aura-bot

7.1.1. dialogContext model

Property	Type	Description	Applicable Aura Platform components
normalizeTerms	boolean	It normalizes the options of `dialogContext` before trying to match. By default: `true`	aura-bot
disabled	boolean	It disables the generation of `dialogContext`. Default: `false`	aura-bot
disabledMerge	boolean	It disables the use of the custom `dialogContext`. If a custom `dialogContext` exists, this won’t be merged with the auto-generated. By default: `false`	aura-bot
processFromClient	boolean	It processes the dialogContext sent in the `channelData` of client message. By default: `false`	aura-bot
returnToClient	boolean	It sends the current dialogContext in the `channelData` to the client message. By default: `false`	aura-bot
defaultListType	defaultListType model	Improved recognition of numbers.	aura-bot
promptChoice	dialogContextGenerated model	Object of dialogContextGenerated	aura-bot
cardActions	dialogContextGenerated model	Object of dialogContextGenerated	aura-bot

7.1.1.1. defaultListType model

Property	Type	Description	Applicable Aura Platform components
DefaultListType	enum	- `none`: no generated list - `ordinal`: only ordinal values are generated and will be included in the `text` field of the dialogContext - `cardinal`: only the list of cardinals for each dialogContext option will be generated - `ordinalCardinal`: both ordinal and cardinal values for each dialogContext option are generated	aura-bot

7.1.1.2. dialogContextGenerated model

Property	Type	Description	Applicable Aura Platform components
generate	generateType model	Value representing when the list is generated	aura-bot
generateList	boolean	Boolean value to indicate if the list is generated	aura-bot

7.1.1.2.1. generateType model

Property	Type	Description	Applicable Aura Platform components
Generate	enum	- `never`: No lists are generated for `dialogContext` options. If this property is at channel level, options in Prompts and CardActions will be ignored - `always`: The list will always be generated - `custom`: If the channel has this value, then it will depend on the configuration of each Prompt or CardAction	aura-bot

7.1.2. responseOptionsVersion model

Property	Type	Description	Applicable Aura Platform components
key	string	Bot response version with the format: `v1`, `v2`, `v3`, etc.	aura-bot
value	responseOptionsVersionParameters	Bot response mode for that version	aura-bot

7.1.2.1. responseOptionsVersionParameters model

Property	Type	Description	Applicable Aura Platform components
batchMessages	boolean	If batchMessages will be used	aura-bot
singleMessage	boolean	If singleMessage will be used	aura-bot
defaultDirectlineVersion	boolean	Flag to indicate if messages should be sent in this version between aura-bridge and aura-bot. Only one version can be set as default	aura-bridge

7.1.3. callbackOptions model

Property	Type	Description	Applicable Aura Platform components
url	string	Callback URL to send responses from Auraline	aura-bridge
headers	callbackOptionsHeaders	Headers sent in the callback request	aura-bridge
refreshOptions	refreshOptions	Configurations needed to refresh authorization token if needed	aura-bridge

7.1.3.1. CallbackOptionsHeaders model

Property	Type	Description	Applicable Aura Platform components
authorization	string	Authorization header sent in the request	aura-bridge

7.1.3.2. refreshOptions model

Property	Type	Description	Applicable Aura Platform components
refreshToken	string	Token used to refresh authorization token	aura-bridge
expiresAt	string	Date of token expiration in ISO 8601 format	aura-bridge
refreshTokenUrl	string	Endpoint to refresh token	aura-bridge
clientId	string	Oauth clientId	aura-bridge
clientSecret	string	Oauth secret	aura-bridge
redirectUri	string	Oauth redirect uri	aura-bridge

Property	Type	Description	Applicable Aura Platform components

7.1.4.1. disambiguationOptions model

Property	Type	Description	Applicable Aura Platform components
returnScore	boolean	Flag to return the score from disambiguation in NLP as a Service	aura-gateway-api

8.1. security model

Property	Type	Description	Applicable Aura Platform components
anonymous	string	Type of anonymous users that this channel handles. Values: - `anonymous`: unauthenticated user - `identifiable`: the channel `userId` univocally identifies a user in the channel	aura-bot
allowUserProfile	boolean	Flag to indicate whether or not `UserProfile` Kernel API must be called during the authentication process. Values: - `True`, if authentication allows calling `UserProfile` Kernel API - `False`, if authentication does not allow calling `UserProfile` Kernel API	aura-bot
anonymousSettings	anonymousSettings	Settings for checking user profile on anonymous users	aura-bot
channelId	string	Readable channel identifier, resulting from the consolidation of the C360 and Telco listings, used for security purposes	aura-bot, aura-authentication-api
authScopes	string	Blank separated list of the scopes needed by the users of this channel to request an access token to Kernel in order to access the corresponding APIs	aura-bot
authPurposes	string	Blank separated list of the purposes needed by the users of this channel to request an access token to Kernel in order to access the corresponding APIs	aura-bot
federatedAuthentication	federatedAuthentication	Model with the information to handle integrated authentication for its users	aura-bot, aura-authentication-api
termsAndConditions	termsAndConditionsConfiguration	Set of settings needed to activate Terms and Conditions in the channel	aura-bridge

8.1.1. anonymousSettings model

Property	Type	Description	Applicable Aura Platform components
enableUserProfile	boolean	`true` means that user profile API will be requested for anonymous users, to check if current phone number is corporate. `false` or empty will not check user profile API	aura-bot
checkPromptedNumber	boolean	`true` means that user profile API will be requested to check if prompted phone number is corporate. `false` or empty will not check user profile API for prompted phone numbers	aura-bot

8.1.2. federatedAuthentication model

Property	Type	Description	Applicable Aura Platform components
loginUrl	string	String with the IdBroker URL to be used to authenticate this channel users. If not set, the requests will be sent to `AURA_BOT_DIALOG_ACCOUNT_LINKING_URL` environment configuration	aura-bot
auraIdSeparator	string	Separator to be used in aura-authentication-api to store the `auraId` of the user: `<channelName><separator><channelUserId>`. This format is used to avoid overlapping of `userIds` from different channels	aura-bot
loginCallback	loginCallback	Object with the configuration of the channel callback that will be requested with the authentication result by aura-authentication-api, to finish the authentication process	aura-authentication-api
logoutCallback	logoutCallback	Object with the configuration of the logout callback to delete session data or delete cookies from the browser	aura-bot, aura-authentication-api
authorizationIdExpiration	number	Expiration time of users in seconds. If not configured, users will expire by `authorizationId` in Kernel as usual.	aura-bot, aura-authentication-api

8.1.2.1. loginCallback model & logoutCallback model

Property	Type	Description	Applicable Aura Platform components
method	string	HTTP method, usually, `get` or `post`, to be used to make the callback request	aura-authentication-api
integrated	string	Flag to indicate whether the authentication response to be returned to the user is directly the response of the `channel_communication_endpoint` request or not	aura-authentication-api
endpoint	string	Channel authentication callback endpoint	aura-authentication-api
queryParams	string	Query params to be sent in the request to the authentication callback endpoint, if needed, if `method` is `GET` and `queryparams` are needed	aura-authentication-api
headers	array	Array of string with the HTTP headers to be sent in the request to the authentication callback endpoint	aura-authentication-api
body	string	String with the body to be returned in the request to the authentication callback endpoint, if needed, if `method` is `POST` and a `body` is needed. If the body is a JSON object, it should go `stringified`	aura-authentication-api

8.1.3. termsAndConditionsConfiguration model

Property	Type	Description	Applicable Aura Platform components
authenticated	termsAndConditionsModel	T&C settings for authenticated users	aura-bot
anonymous	termsAndConditionsModel	T&C settings for anonymous users	aura-bot

8.1.3.1. termsAndConditionsModel model

Property	Type	Description	Applicable Aura Platform components
service	string	Name of the service where the T&C will be stored	aura-bot
version	string	Version of the service where the T&C will be stored	aura-bot

9.1. WhatsApp model

Property	Type	Description	Applicable Aura Platform components
client	whatsappClient	Necessary information for Kernel WhatsApp client	aura-bridge, Aura Filemanager
phoneNumber	string	WhatsApp phone number of the channel. Used to redirect the user to WhatsApp conversation in HTML templates	aura-bot
listOptions	listOptions	Conversion of prompts and suggestions that use HeroCard to WhatsApp lists	aura-bridge

9.1.1. whatsApp client model

Property	Type	Description	Applicable Aura Platform components
id	string	Kernel WhatsApp client identifier	aura-bridge, aura-file-manager
secret	string	Kernel WhatsApp client secret	aura-bridge, aura-file-manager
purposes	string	Kernel WhatsApp client purposes	aura-bridge, aura-file-manager
scopes	string	Kernel WhatsApp client scopes	aura-bridge, aura-file-manager
version	string	Kernel WhatsApp API version (v1, v2)	aura-bridge

9.1.2. listOptions model

This model defines the conversion of prompts and suggestions that use HeroCard into WhatsApp lists.

Property	Type	Description	Applicable Aura Platform components
type	string	WhatsApp list type. Allowed values: `button`, `enumeratedList`, `list`	aura-bridge
rules	listOptionsRule	Conversion rules to WhatsApp lists	aura-bridge

9.1.2.1. listOptionsRule model

This model defines the conversion of rules into WhatsApp lists.

Property	Type	Description	Applicable Aura Platform components
type	string	WhatsApp list type. Allowed values: `button`, `enumeratedList`, `list`	aura-bridge
resources	listOptionsResource model	Definition of the resources used in the WhatsApp lists	aura-bridge

9.1.2.1.1. listOptionsResource model

Property	Type	Description	Applicable Aura Platform components
name	string	Name of resource	aura-bridge
resourceKey	string	Resource key	aura-bridge

10.1 ATRIA model

Property	Type	Description	Applicable Aura Platform components
dialogs	atriaDialogConfig	ATRIA configuration by dialog	aura-bot
recognizers	atriaRecognizerConfig	ATRIA configuration by intent	aura-bot

10.1.1 ATRIA Dialog config

Property	Type	Description	Applicable Aura Platform components
dialog string key	atriaDialogConfig	ATRIA configuration by key dialog	aura-bot

10.1.2 ATRIA Recognizer config

Property	Type	Description	Applicable Aura Platform components
intent string key	atriaIntentConfig	ATRIA configuration by key intent	aura-bot

10.1.1 ATRIA intent config

Property	Type	Description	Applicable Aura Platform components
applicationId	string	ATRIA application identifier	aura-bot
presetId	string	ATRIA preset identifier	aura-bot

Example

export interface ChannelConfiguration {
    auraBotCacheTTL?: number;
    id: string;
    name: string;
    prefix: string;
    security?: {
        anonymous: 'anonymous' | 'identifiable';
        allowUserProfile: boolean;
        channelId: string;
        authPurposes: string;
        authScopes: string;
        federatedAuthentication?: {
            loginUrl: string;
            auraIdSeparator: string;
            loginCallback: {
                method: string;
                integrated: string;
                endpoint: string;
                queryParams?: string;
                headers?: [string];
                body?: string;
            };
            logoutCallback: {
                method: string;
                integrated: string;
                endpoint: string;
                queryParams?: string;
                headers?: [string];
                body?: string;
            };
        };
        termsAndConditions: {
            authenticated: {
                version: string;
                service: string;
            };
            anonymous: {
                version: string;
                service: string;
            };
        };
    };
    nlp?: {
        enabled: boolean;
            enabled: boolean;
            custom: boolean;
            azureContainerURL?: string;
            e2eBlockThreshold?: number;
            e2eWarningThreshold?: number;
        };
    };
    whatsapp?: {
        client: {
            id: string;
            secret: string;
            purposes?: string;
            scopes?: string;
        };
        phoneNumber?: string;
    };
    type?: 'whatsapp' | 'auraline';
    actions?: {
        afterLogin?: {
            action: string;
            type: string;
            data: any | {
                originIntent: any;
            };
        };
        thirdPartyApp?: {
            action?: string;
            type?: string;
            data?: any;
            contentType?: string;
        };
    };
    requestOptions?: {
        fileAttachments?: {
            enabled: boolean;
            enabledExtensions?: string[];
            customProactiveDialogId?: string;
            validations?: {
                [type: string]: {
                    size: {
                        min?: number;
                        max?: number;
                    };
                };
            };
        };
        requestOptionsVersion?: any;
    }
    responseOptions?: {
        dialogContext: {
            disabled: boolean;
            disabledMerge: boolean;
            normalizeTerms: boolean;
            defaultListType: 'none' | 'ordinalCardinal' | 'ordinal' | 'cardinal';
            promptChoice: {
                generate: 'never' | 'always' | 'custom';
                generateList: boolean;
            };
            cardActions: {
                generate: 'never' | 'always' | 'custom';
                generateList: boolean;
            };
            returnToClient?: boolean;
            processFromClient?: boolean;
        };
        versions?: {
            [key: string]: {
                batchMessages?: boolean;
                singleMessage?: boolean;
            };
        };
        needsEmptyResponseEvent?: boolean;
        outputMessageFormat: 'custom' | 'enrich' | 'html5' | 'simple' | 'voice';
        sendSpeak: boolean;
        disambiguationFormat?: 'disabled' | 'prompts' | 'suggestions';
    };
    dialogLibraries: [{
        name: string;
        authorization?: {
            scopes?: string;
            purposes?: string;
            [name: string]: string;
        };
        dialogs: [{
            id: string;
            triggerConditions: [{
                contextFilters?: [{
                    conditions: string;
                    false: {
                        breakDialogExecution: boolean;
                        breakFilterEval: boolean;
                        name: string;
                        resource: string;
                        suggestions?: boolean;
                        redirectToIntent?: string;
                        originalIntent?: string;
                    };
                    name: string;
                    true: {
                        breakDialogExecution: boolean;
                        breakFilterEval: boolean;
                        name: string;
                        resource: string;
                        suggestions?: boolean;
                        redirectToIntent?: string;
                        originalIntent?: string;
                    };
                    type: string;
                }];
                intent: string;
                entity?: string;
                settings?: {
                    type?: string;
                    action?: string;
                    locales?: {
                        success?: string[];
                        error?: string[];
                    };
                    payload?: any;
                    addEntitiesToPayload?: boolean;
                    needPlayingContent?: boolean;
                    sound?: 'positive' | 'negative' | 'none';
                    needTvResolution?: boolean;
                    confirmSuggestion?: boolean;
                    resolutionIntent?: string;
                    resolutionEntities?: any[];
                    payloadType?: 'tv' | 'communications'| 'wifi' | 'radio';
                    isFullscreen?: boolean;
                };
            }];
            channelDataVersion?: string;
            prefix?: string;
            suggestions?: boolean;
            allowAnonymous?: boolean;
            authorization?: {
                scopes?: string;
                purposes?: string;
                [name: string]: string;
            };
        }];
    }];
}

Docs:

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

channelData v1

Specification for channelData v1 model used by Aura Bot to work with the different channels

Introduction

In older Aura Platform releases, the default version was version v1, so some channels did not send the version of the channelData and aura-bot handled their requests as version v1.

There is an exception: in release Aerosmith, aura-bot included Living Apps handling as a platform feature.

Learn how to manage errors in v1 here

JSON schema for channelData v1 request model

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "resource:/aura-models/channel-data/1.0.0/request/channeldata-1.0.0-request.schema#",
    "$ref": "#/definitions/aura/bot/1.0.0/request/ChannelData",
    "$version": "1.0.0",
    "definitions": {
        "aura": {
            "bot": {
                "1.0.0": {
                    "request": {
                        "ChannelData": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "fullAura": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/FullAura"
                                },
                                "allowed": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "appContext": {
                                    "description": "This property contains application context data to let the Aura bot instance adapt its response to the characteristics of the application being used by the Telefónica client to interact with Aura. It contains both general properties and specific properties for TV channels.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/AppContext"
                                },
                                "auraCommand": {
                                    "description": "This property makes it possible to send a specific intent to the Aura bot on behalf of the Telefónica client interacting with Aura. Consequently, the message contents do not need to be analysed to recognize the Telefónica client intent.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/AuraCommand"
                                },
                                "auraMode": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/AuraMode"
                                },
                                "customAuraContent": {
                                    "type": "boolean"
                                },
                                "imageMaxWidth": {
                                    "type": "number"
                                },
                                "correlator": {
                                    "description": "This property contains an UUID uniquely identifying the concrete request sent through the channel. This unique identifier is of great help when doing cross system analysis, as a way to correlate the actions executed by distinct elements of the whole system associated to the fulfilment of the same request. In case the correlator property is not provided, the Aura bot will generate one and pass it over in any interaction with any external component.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "dialogContext": {
                                    "description": "This property must only be included in the request every time the previous response from the AuraBot contains a dialogContext. The channel would just copy the very same object in its following request to AuraBot. The dialogContext contains extra information to contextualize the next request as part of a whole conversation (even as part of a set of conversations) so Aura bot is able to behave in a much more similar way to human's behaviour when establishing and maintaining conversations. If the dialogContext property is set in the request, it will be used during the bot recognition phase to find the intention of the user directly. It is as a hidden menu for the dialog being executed that allows extra straightforward recognitions.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/DialogContext"
                                },
                                "imageSettings": {
                                    "description": "This property makes it possible to provide information about the graphical screening capabilities exposed by the application used by the Telefónica client to interact with the Aura bot instance. The contents of this property are typically used to optimize the graphical content sent by the Aura bot instance to the application finally showing the graphical information sent.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/ImageSettings"
                                },
                                "version": {
                                    "description": "This property encodes the version of the Aura Request – Response Semantic Model being used, so the structural dependencies and semantics of the data provided can be properly managed.",
                                    "type": "string",
                                    "pattern": "^[0-9]+.[0-9]+.[0-9]+$"
                                }
                            },
                            "required": [
                                "appContext",
                                "dialogContext",
                                "version"
                            ],
                            "title": "ChannelData"
                        },
                        "FullAura": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "voice": {
                                    "type": "boolean"
                                },
                                "fullScreenAdvisor": {
                                    "type": "boolean"
                                },
                                "cards": {
                                    "type": "string"
                                }
                            },
                            "title": "FullAura"
                        },
                        "AppContext": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "application": {
                                    "description": "This property includes information about the characteristics of the application being used by the Telefónica client to interact with the Aura bot instance. Also generally speaking is Optional (but recommended). It contains both general sub-properties and specific ones for TV channels In Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Application"
                                },
                                "channel": {
                                    "description": "This property includes information about the channel being used by the Telefónica client to interact with the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Channel"
                                },
                                "device": {
                                    "description": "This property includes Information about the physical device used by the Telefónica client to interact with the Aura bot instance. Also generally speaking is optional (but recommended). In Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Device"
                                },
                                "location": {
                                    "description": "This property includes information about the location where the user is located. Also generally speaking is optional (but recommended). In Spain, it is a mandatory parameter for TV use cases, if not sent logical.unknown location will be used.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Location"
                                },
                                "userContext": {
                                    "description": "[TV] This property includes information about the user associated to the Telefónica client interacting with the Aura bot instance. This information can be used to customize the response sent back by the Aura bot instance to the specific Telefónica client. Although generally speaking, this parameter is optional.  It is a general property, but for the current model, it is only applied for TV use cases. In fact, in Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/UserContext"
                                },
                                "contextFilters": {
                                    "description": "This property includes information in a string array format which may be used to filter the final response sent by the Aura bot instance back to the Telefónica client. For example, to determine the most appropriate answer to a generic question. The format of each entry of the array should be key:value, where both key and value are application dependant.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "timestamp": {
                                    "description": "This property includes an ISO 8601 formatted string with the exact local time instant when the request was sent. It should contain the local time including the corresponding time zone.",
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "timezone": {
                                    "description": "This property includes the time zone from where the Telefónica client is interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "livingApp": {
                                    "description": "[LA] This property includes the time zone from where the Telefónica client is interacting with the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/LivingApp"
                                }
                            },
                            "required": [
                                "channel"
                            ],
                            "title": "AppContext"
                        },
                        "Application": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "playMode": {
                                    "description": "[TV] For the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player (such as a TV), this property states if the access if being made by the concrete media player device or by an external app where the content is embedded and played.",
                                    "type": "string",
                                    "enum": [
                                        "LOCALE",
                                        "REMOTE"
                                    ]
                                },
                                "type": {
                                    "type": "string"
                                },
                                "playing": {
                                    "description": "[TV] This property includes information about the content being played for the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player such as a TV or a channel abled to be linked with a TV.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Playing"
                                },
                                "screenId": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/ScreenId"
                                }
                            },
                            "title": "Application"
                        },
                        "ScreenId": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "type": {
                                    "type": "string"
                                },
                                "ucid": {
                                    "type": "string"
                                },
                                "vod": {
                                    "type": "boolean"
                                }
                            },
                            "title": "ScreenId"
                        },
                        "Playing": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "id": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: - false, if the content cannot be recorded. (unique possible value if 'type' is VoD) - true, if the content can be recorded.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "Type of content being played.",
                                    "type": "string",
                                    "enum": [
                                        "live",
                                        "vod",
                                        "l7d",
                                        "record"
                                    ]
                                },
                                "recordingAllowed": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: - false, if the content cannot be recorded. (unique possible value if 'type' is VoD) - true, if the content can be recorded.",
                                    "type": "number"
                                },
                                "startOver": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: - false, if the content cannot be recorded. (unique possible value if 'type' is VoD) - true, if the content can be recorded.",
                                    "type": "number"
                                },
                                "currentAudioID": {
                                    "description": "This property states the audio language selected by the Telefónica client to play the associated content. The value of this property must be one of the keys included in the audioList property.",
                                    "type": "string"
                                },
                                "currentSubtitlesID": {
                                    "description": "This property states the subtitles language selected by the Telefónica client to play the associated content. The value of this property must be one of the keys included in the subtitlesList property. If no subtitles are selected, this property should not be included.",
                                    "type": "string"
                                },
                                "audioList": {
                                    "description": "This property includes an object whose values are 3-letters codes (ISO 639-2) stating the available audio language.",
                                    "type": "object"
                                },
                                "subtitlesList": {
                                    "description": "This property includes an object whose values are 3-letters codes (ISO 639-2) stating the available subtitles language.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "type",
                                "id"
                            ],
                            "title": "Playing"
                        },
                        "Channel": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "appId": {
                                    "description": "This property includes a unique identifier in UUID format which uniquely identifies the channel in Aura. The UUID is the same for all OBs. This identifier must be provided by Aura Operations Team to the channel.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "modality": {
                                    "description": "This property describes the way the Telefónica client used to interact with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "AUDIO",
                                        "VOICE",
                                        "TEXT",
                                        "TACTILE",
                                        "COMMAND",
                                        "FORM"
                                    ]
                                }
                            },
                            "required": [
                                "appId",
                                "modality"
                            ],
                            "title": "Channel"
                        },
                        "Device": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "deviceId": {
                                    "description": "This property includes a unique identifier of the device the Telefónica client used to interact with the Aura bot instance. This id must be already registered in the backends of the OB.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "This property states the type of device used by the Telefónica client used to interact with the Aura bot instance. The possible values should be aligned with the APIs backend to ensure that contents will be returned.",
                                    "type": "string"
                                },
                                "interfaceLanguage": {
                                    "description": "This property includes a combination of ISO-3166 2-letters country codes and ISO 639-1 2-letter language code separated by a hyphen stating the language used by the Telefónica client to interact with the concrete Aura bot instance.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "deviceId",
                                "type"
                            ],
                            "title": "Device"
                        },
                        "Location": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "logical": {
                                    "description": "This property describes the location from where the Telefónica client interacts with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "home",
                                        "outside",
                                        "unknown"
                                    ]
                                }
                            },
                            "title": "Location"
                        },
                        "UserContext": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "userAccountNumber": {
                                    "description": "This property includes an identifier uniquely identifying the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "userProductList": {
                                    "description": "This property includes a list of the products available in the active contract for the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "userProfile": {
                                    "description": "This property describes the commercial offer chosen by the Telefónica client interacting with the Aura bot instance. This property only applies in the case of Spain for STB, Movistar Home and Movistar Plus channels.",
                                    "type": "string"
                                },
                                "userPurchaseList": {
                                    "description": "List with the content purchased by the user (tVOD).",
                                    "type": "string"
                                },
                                "userSTBList": {
                                    "description": "This property includes the list of STBs which belongs to the Telefónica client interacting with the Aura bot instance.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/STBType"
                                    }
                                }
                            },
                            "required": [
                                "userAccountNumber",
                                "userSTBList"
                            ],
                            "title": "UserContext"
                        },
                        "STBType": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "deviceId": {
                                    "description": "This property includes the device identifier of the STB.",
                                    "type": "string"
                                },
                                "model": {
                                    "description": "This property includes the device model of the STB.",
                                    "type": "string"
                                },
                                "friendlyName": {
                                    "description": "This property includes a printable name of the STB device. This can be modified by the user using the STB UI.",
                                    "type": "string"
                                },
                                "remote_play_allowed": {
                                    "description": "This property includes a boolean value (this is, true or false) describing if the STB device allows the possibility of playing content launched from a remote entity such as a mobile application.",
                                    "type": "boolean"
                                },
                                "remote_play_on": {
                                    "description": "This property includes a boolean value (this is, true or false) describing if the STB device is on or off.",
                                    "type": "boolean"
                                },
                                "maxQuality": {
                                    "description": "Highest video quality of the device.",
                                    "type": "string",
                                    "enum": [
                                        "highDefinition",
                                        "lowDefinition",
                                        "standardDefinition",
                                        "UHD_4K"
                                    ]
                                }
                            },
                            "required": [
                                "deviceId"
                            ],
                            "title": "STBType"
                        },
                        "LivingApp": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "id": {
                                    "description": "This property includes an identifier uniquely identifying (UUID) the Living App in Aura.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "description": "This property includes a semantic identifier uniquely identifying the Living App in Aura.",
                                    "type": "string"
                                },
                                "prefix": {
                                    "description": "This property includes the short name associated to the Living App",
                                    "type": "string"
                                },
                                "sessionId": {
                                    "description": "This property includes an identifier uniquely identifying the session associated to the Living App in Aura. The  sessionId property must be sent if it was previously received in the start-living-appevent response message.",
                                    "type": "string"
                                },
                                "prettyName": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "id",
                                "name",
                                "prefix",
                                "sessionId"
                            ],
                            "title": "LivingApp"
                        },
                        "AuraCommand": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "type": {
                                    "description": "This property includes the type of Aura command sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "intent",
                                        "suggestion",
                                        "notification",
                                        "operation",
                                        "text",
                                        "event"
                                    ]
                                },
                                "value": {
                                    "description": "This property includes the data needed to execute the command. Its content depends on the type of Aura command.",
                                    "anyOf": [
                                        {
                                            "$ref": "#/definitions/aura/bot/1.0.0/request/SuggestionIntentOperationValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/1.0.0/request/NotificationValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/1.0.0/request/EventValue"
                                        },
                                        {
                                            "type": "string"
                                        }
                                    ]
                                },
                                "utm": {
                                    "description": "It shows the exact interface element that was used by the user to launch the auraCommand.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Utm"
                                }
                            },
                            "required": [
                                "type",
                                "value"
                            ],
                            "title": "AuraCommand",
                            "allOf": [
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "pattern": "intent|suggestion|operation"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/1.0.0/request/SuggestionIntentOperationValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "notification"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/1.0.0/request/NotificationValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "text"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "event"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/1.0.0/request/EventValue"
                                            }
                                        }
                                    }
                                }
                            ]
                        },
                        "SuggestionIntentOperationValue": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference which will determine the Aura dialog to execute. The format of this property is: intent.<libraryId>.<intentId> In case the prefix intent. is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: - type:  this property includes a string stating the type of entity. - entity: this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/Entity"
                                    }
                                }
                            },
                            "required": [
                                "intent"
                            ],
                            "title": "SuggestionIntentOperationValue"
                        },
                        "NotificationValue": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "action": {
                                    "description": "This property includes the Aura intention reference informing of the dialog to be executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>.",
                                    "type": "string"
                                },
                                "notificationData": {
                                    "description": "This property includes detailed information about the notification being sent to the Telefónica client. The data sent will let Aura predict unusual behaviour in clients billing, balance or data consumption.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "action",
                                "notificationData"
                            ],
                            "title": "NotificationValue"
                        },
                        "EventValue": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference informing of the dialog to be executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: - type:  this property includes a string stating the type of entity. - entity: this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/Entity"
                                    }
                                },
                                "text": {
                                    "description": "User utterance.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "Event type: local-grammar.",
                                    "type": "string"
                                },
                                "payload": {
                                    "description": "Specific per event type.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "type"
                            ],
                            "title": "EventValue"
                        },
                        "Utm": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "source": {
                                    "description": "It identifies which site sent the traffic. Please, use the channel name.",
                                    "type": "string"
                                },
                                "medium": {
                                    "description": "It identifies what type of link was used, such as cost per click or email.",
                                    "type": "string"
                                },
                                "campaign": {
                                    "description": "It identifies a specific product promotion or strategic campaign.",
                                    "type": "string"
                                },
                                "term": {
                                    "description": "It identifies search terms. We still need to define the content of this field.",
                                    "type": "string"
                                },
                                "content": {
                                    "description": "It identifies what specifically was clicked to bring the user to the site, such as a banner ad or a text link.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "source"
                            ],
                            "title": "Utm"
                        },
                        "AuraMode": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "fullAura": {
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/FullAura"
                                }
                            },
                            "title": "AuraMode"
                        },
                        "DialogContext": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "text": {
                                    "description": "This property includes the word to be recognized. In forthcoming releases of Aura, the contents of this property will be upgraded to a pipe separated list of recognizable words.",
                                    "type": "string"
                                },
                                "value": {
                                    "description": "This property includes the data needed to execute the command.",
                                    "$ref": "#/definitions/aura/bot/1.0.0/request/Value"
                                }
                            },
                            "title": "DialogContext"
                        },
                        "Value": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference which will determine the Aura dialog to execute. The format of this property is: intent.<libraryId>.<intentId>. In case the prefix intent. is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: - type:  this property includes a string stating the type of entity. - entity: this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/1.0.0/request/Entity"
                                    }
                                }
                            },
                            "required": [
                                "intent",
                                "entities"
                            ],
                            "title": "Value"
                        },
                        "Entity": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "canon": {
                                    "description": " This property includes the canonical form of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "endIndex": {
                                    "description": "The index at which this entity ends in the original user message.",
                                    "type": "number"
                                },
                                "entity": {
                                    "description": "This property includes the value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "label": {
                                    "description": "This property includes an internally used descriptive tag of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "score": {
                                    "description": "This property includes the accuracy (in per 1 units) of the recognized entity sent on behalf of the Telefónica client interacting with the Aura bot instance. In the case of Aura commands this value should be 1 since in this case fully recognized intentions are sent.",
                                    "type": "number"
                                },
                                "startIndex": {
                                    "description": "The index at which this entity starts in the original user message.",
                                    "type": "number"
                                },
                                "type": {
                                    "description": "This property includes the type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance. The format used by this property is the following one: ent.<entityType>",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "canon",
                                "entity",
                                "score",
                                "type"
                            ],
                            "title": "Entity"
                        },
                        "ImageSettings": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                                "graphicsWidth": {
                                    "description": "his property indicates the recommended width in pixels of the images the Aura bot instance should sent to the Telefónica client according to the communication means she is using to interact with Aura. The default value is 500.",
                                    "type": "number"
                                },
                                "resolution": {
                                    "description": "This property indicates the recommended scaling factor the Aura bot instance should apply to the images sent to the Telefónica client. The default value is mdpi.",
                                    "type": "string",
                                    "enum": [
                                        "mdpi",
                                        "hdpi",
                                        "xhdpi",
                                        "xxhdpi",
                                        "xxxhdpi"
                                    ]
                                }
                            },
                            "title": "ImageSettings"
                        }
                    }
                }
            }
        }
    }
}

Docs:

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

Agents Manager communication protocol

Description of Agents Manager communication protocol

Communication protocol

The agents-manager uses a synchronous communication protocol, although the specific behavior may vary depending on the endpoint. The following diagram illustrates the protocol:

agents-manager communication protocol

Docs:

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

Status in channelData v3

List of the status returned by Aura with channelData model v3

Introduction

The status field represents how the request made to Aura has worked, trying to summarize if it has been successful or it has failed and the reason for it.

⚠️ All cases described as future-case are currently not implemented, although in future releases this could change.

How to use status in v3

import { AURA_STATUS_V3 } from '@telefonica/aura-utilities/lib/aura-models';
import { AuraResponseStatusV3 } from '@telefonica/aura-bot-utilities/lib/aura-bot-common';

channelData.status = new AuraResponseStatusV3(AURA_STATUS_V3.SUCCESS, correlator);
console.log(channelData.status);
/* Prints
{
    code: 'SUCCESS',
    message: 'Success'
}
*/

If you need a status with parameters, add it as a third parameter:

channelData.status = new AuraResponseStatusV3(AURA_STATUS_V3.ERROR.CHANNELDATA.VALIDATING, correlator, {appName: 'FakeApp'});
console.log(channelData.status);
/* Prints
{
    code: 'ERROR.CHANNELDATA.VALIDATING',
    message: 'App dialogs are not installed'
    params: {
      appName: 'FakeApp'
    }
}
*/

Parameters should match the definition of the status. If not, some errors will be logged:

With missing parameters:

channelData.status = new AuraResponseStatusV3(AURA_STATUS_V3.ERROR.CHANNELDATA.VALIDATING, correlator);
/* Error logged
ERROR: `Missing parameter in status constructor`
STCK: {
 status: {
    code: 'ERROR.CHANNELDATA.VALIDATING',
    message: 'App dialogs are not installed',
    params: ['appName']
 },
 params: undefined
}

With wrong parameters:

channelData.status = new AuraResponseStatusV3(AURA_STATUS_V3.ERROR.CHANNELDATA.VALIDATING, correlator, { appName: 'TestApp', reason: 'WRONG_REASON'});
/* Error logged
ERROR: `Invalid parameter reason in status constructor`
STCK: {
 status: {
    code: 'ERROR.CHANNELDATA.VALIDATING',
    message: 'Error handling terms and conditions',
    params: ['appName', { reason: [ 'CANNOT_CHECK', 'CANNOT_UPDATE']}]
 },
 params: { appName: 'TestApp', reason: 'WRONG_REASON'}
}

With extra parameters, there is no error logged. You can add all the extra params you require:

channelData.status = new AuraResponseStatusV3(AURA_STATUS_V3.SUCCESS, correlator, { allOk: 'Yes, sure' });
console.log(channelData.status);
/* Prints
{
    code: 'SUCCESS',
    message: 'Success',
    params: {
      allOk: 'Yes, sure'
    }
}

List of status returned by Aura Bot

Success status

Code	Message
SUCCESS	Success

TV Channel

Code	Message	Description
SUCCESS.NO_CONTENT	Success with no content	This success occurs when the response does not include any content but the request was successful.

Error status

ChannelData

Code	Params	Message	Description
ERROR.CHANNELDATA.VALIDATING	errors (array of invalid fields/values in channelData)	`channelData` validation error	This error occurs when the `channelData` sent in the request does not follow the request channelData v3 schema.

Context

Code	Params	Message	Description
ERROR.CONTEXT.VALIDATING	errors (invalid fields/values)	`channelData` context validation error	`future case`. This error occurs when the context being validated has a wrong format.

Target

Code	Params	Message	Description
ERROR.TARGET	target reason: [NOT_EXIST, NOT_ALLOWED, UNLIKED, OTHER] [key:value]	Action Target Error	See Params cases for more information.

Target error params cases

Code	Message	Description
NOT_EXIST	Action Target Error	If there is no valid STB ID and `channelData.appContext.location.logical === 'home'`, then `NOT_EXIST` is returned.
UNLIKED	Action Target Error	If STB ID exists and is valid and `channelData.appContext.location.logical === 'home'`, but there is no `channelData.appContext.application.playing`.
OTHER	Action Target Error	`future case`. Other errors.

Content

Code	Message	Description
ERROR.CONTENT.NOT_INCLUDED	Action Target Error	`future case`. This error occurs when an action has no target.

TV Channel

Code	Message	Description
ERROR.TV_CHANNEL.NOT_INCLUDED	TV Channel not included	`future case`. This error occurs when the TV channel supplied in the request is not included.
ERROR.TV_CHANNEL.NOT_SUPPORTED	TV Channel not supported	`future case`. This error occurs when the TV channel supplied in the request is not supported.
ERROR.INVALID_REQUEST	TV Channel invalid request	`future case`. This error occurs when the request is not a valid request.
ERROR.CONTENT.NOT_FOUND	TV Channel content not found	`future case`. This error occurs when the TV channel supplied in the request is not found.

Entities

Code	Params	Message	Description
ERROR.ENTITIES	reason: [INCOMPATIBLE, NOT_SUPPORTED] [type, entity]	Entities Error	`future case`. This error occurs if there is a problem with the entities provided.

Intent

Code	Params	Message	Description
ERROR.INTENT	reason: [NOT_SUPPORTED]	Intent not Supported Error	This error occurs if the intent informed in the request is not configured for the channel.

User

Code	Params	Message	Description
ERROR.USER.UNAUTHENTICATED	auraId	Invalid aura user	This error occurs if the user informed in the request is not correctly formatted or does not exist.
ERROR.USER.FORBIDDEN	reason: error log	User profile or consents error	`future case`. This error occurs if the user has been forbidden.

Internal

Code	Params	Message	Description
ERROR.INTERNAL	reason: error log	Internal Error	This error occurs if an external API returns an error, which is being propagated in the `reason` param or there is an internal error in aura-bot.

Docs:

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

JSON schema for channelData v3 request model

Description of the JSON schema for channelData v3 request model

General conventions

Properties corresponding to the request model can be general (applicable for all channels) or specific for TV channels. In order to identify the type(s) of each property, regarding the abovementioned classification, the following symbols will be used in the JSON schemas:

Types of properties	Tags in JSON schemas
General property (applicable for all channels)	No tag in description
Specific property for TV channels Currently: Movistar Plus, Movistar Home, STB	Tag [TV] in description

The mandatory parameters are included in the field required of each property in the corresponding JSON files.

JSON schema for channelData v3 request model

{
    "$schema": "http://json-schema.org/schema#",
    "$id": "resource:/aura-models/channel-data/3.2.0/request/channeldata-3.2.0-request.schema#",
    "$ref": "#/definitions/aura/bot/3.2.0/request/RequestChannelData",
    "$version": "3.2.0",
    "definitions": {
        "aura": {
            "bot": {
                "3.2.0": {
                    "request": {
                        "RequestChannelData": {
                            "type": "object",
                            "description": "Properties corresponding to the request model can be general (applicable for all channels), specific for TV channels or specific for Living Apps. In order to identify the type(s) of each property, regarding the abovementioned classification, the following symbols will be used in the JSON schemas: General property (No tag in description), Specific property for TV channels Currently: Movistar Plus, Movistar Home, STB (Tag [TV] in description), Specific property for Living Apps (Tag [LA] in description).",
                            "additionalProperties": false,
                            "properties": {
                                "appContext": {
                                    "description": "This property contains application context data to let the Aura bot instance adapt its response to the characteristics of the application being used by the Telefónica client to interact with Aura. It contains both general properties and specific properties for TV channels and Living Apps.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/AppContext"
                                },
                                "auraCommand": {
                                    "description": "This property makes it possible to send a specific intent to the Aura bot on behalf of the Telefónica client interacting with Aura. Consequently, the message contents do not need to be analysed to recognize the Telefónica client intent.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/AuraCommand"
                                },
                                "correlator": {
                                    "description": "This property contains an UUID uniquely identifying the concrete request sent through the channel. This unique identifier is of great help when doing cross system analysis, as a way to correlate the actions executed by distinct elements of the whole system associated to the fulfilment of the same request. In case the correlator property is not provided, the Aura bot will generate one and pass it over in any interaction with any external component.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "imageSettings": {
                                    "description": "This property makes it possible to provide information about the graphical screening capabilities exposed by the application used by the Telefónica client to interact with the Aura bot instance. The contents of this property are typically used to optimize the graphical content sent by the Aura bot instance to the application finally showing the graphical information sent.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/ImageSettings"
                                },
                                "version": {
                                    "description": "This property encodes the version of the Aura Request - Response Semantic Model being used, so the structural dependencies and semantics of the data provided can be properly managed (e.g, 0.1, 0.2, 0.3, 1.0.0, 2.0.0, 3, 4, etc).",
                                    "type": "string",
                                    "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
                                },
                                "payload": {
                                    "description": "Channel data payload information. This property can be used by an external component to aura-bot in order to send information for the enrichment of the request. Information is sent that does not correspond to the bot-framework communication model, but that aura-bot and certain dialogs use to complete processing. Currently it is used by components interacting with the bot through Aura bridge, but it could is used by any component.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "appContext",
                                "version"
                            ],
                            "title": "ChannelData"
                        },
                        "AppContext": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "application": {
                                    "description": "[TV] This property includes information about the characteristics of the application being used by the Telefónica client to interact with the Aura bot instance. It is optional but recommended. It contains both general sub-properties and specific ones for TV channels. In Spain it is a mandatory parameter for TV use cases. It is a general property, but for the current model, it is only applied for TV use cases. In fact, in Spain it is a mandatory parameter for TV use cases",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Application"
                                },
                                "channel": {
                                    "description": "This property includes information about the channel being used by the Telefónica client to interact with the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Channel"
                                },
                                "device": {
                                    "description": "[TV] This property includes Information about the physical device used by the Telefónica client to interact with the Aura bot instance. It is optional but recommended. In Spain it is a mandatory parameter for TV use cases.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Device"
                                },
                                "location": {
                                    "description": "[TV] This property includes information about the location where the user is located. It is optional but recommended. In Spain, it is a mandatory parameter for TV use cases. If not sent, logical.unknown location will be used.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Location"
                                },
                                "user": {
                                    "description": "[TV] This property includes information about the user associated to the Telefónica client interacting with the Aura bot instance. This information can be used to customize the response sent back by the Aura bot instance to the specific Telefónica client. It is a general property, but for the current model, it is only applied for TV use cases. In fact, in Spain it is a mandatory parameter for TV use cases.",
                                    "anyOf": [
                                        {
                                            "$ref": "#/definitions/aura/bot/3.2.0/request/TvUser"
                                        }
                                    ]
                                },
                                "contextFilters": {
                                    "description": "This property includes information in a string array format which may be used to filter the final response sent by the Aura bot instance back to the Telefónica client. For example, to determine the most appropriate answer to a generic question. The format of each entry of the array should be key:value, where both key and value are application dependant.contextfilters for more information.#contextfilters for more information.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "timestamp": {
                                    "description": "This property includes an ISO 8601 formatted string with the exact local time instant when the request was sent. It should contain the local time including the corresponding time zone. For example: 2019-07-01T10:15:30+01:00, for a Europe/Madrid time.",
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "timezone": {
                                    "description": "This property includes the time zone from where the Telefónica client is interacting with the Aura bot instance according to the official time zones (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).",
                                    "type": "string"
                                },
                                "livingApp": {
                                    "description": "[LA] This property includes the time zone from where the Telefónica client is interacting with the Aura bot instance, according to the [official time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/LivingApp"
                                }
                            },
                            "required": [
                                "channel",
                                "timestamp",
                                "timezone"
                            ],
                            "title": "AppContext"
                        },
                        "Application": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "activeApp": {
                                    "description": "This property includes information about the application or third party that is opened in the channel. An example of this is 'netflix' or 'movistar'. The value of the application must be something stipulated between the channels and the developers of use cases in case they want to make a different logic based on this value and it should not depend on the environment. By default, the activeApp is 'movistar'.",
                                    "type": "string"
                                },
                                "countryId": {
                                    "description": "This property includes 2-letters country identifier as defined by the ISO-3166 specification (https://en.wikipedia.org/wiki/ISO_3166) where the Telefónica client is located.",
                                    "type": "string"
                                },
                                "screen": {
                                    "description": "[TV] This property includes information about the screen characteristics used by the Telefónica client to interact with the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Screen"
                                },
                                "thirdParties": {
                                    "description": "This property includes an array of third parties that are available in the application. Each third party is described by a name and an open object with the information that is necessary to interact with the third party.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.2.0/request/ThirdParty"
                                    }
                                },
                                "thirdPartiesContent": {
                                    "description": "Boolean where the channel indicates if contents from third parties are allowed or not in the response. It is an optional field, if not included it is considered as false",
                                    "type": "boolean"
                                },
                                "playing": {
                                    "description": "[TV] This property includes information about the content being played for the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player such as a TV or a channel enabled to be linked with a TV.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Playing"
                                },
                                "playMode": {
                                    "description": "[TV] For the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player (such as a TV), this property states if the access if being made by the concrete media player device or by an external app where the content is embedded and played. The property can have one on these values: 'locale', if content is played in the physical media player device; 'remote', if content is played in an external app.",
                                    "type": "string",
                                    "enum": [
                                        "locale",
                                        "remote"
                                    ]
                                }
                            },
                            "title": "Application"
                        },
                        "Screen": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "elements": {
                                    "description": "It contains both general sub-properties and specific ones for TV channels. For the specific cases when the Telefónica client is interacting with the Aura bot instance through a media player (such as a TV), this property includes information about what it is being shown in the screen.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.2.0/request/Element"
                                    }
                                },
                                "name": {
                                    "description": "This property includes an identifier of the screen or section of the screen the Telefónica customer is interacting through with the Aura bot. The value of this field is open, but it should follow this format: 'rootSection.[childrenSections].pageName'. It should contain a dot-separated list of the section's navigation tree, ending with the current page. For a common understanding, 'home' should be used for the main page of each section.",
                                    "type": "string"
                                }
                            },
                            "title": "Screen"
                        },
                        "Element": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "type": {
                                    "description": "[TV] This property identifies the type of the element. It represents what is shown in the user's screen. In case the element that the channel is describing belongs to a third party (for example Netflix) the element type should be 'thirdPartyContent'.",
                                    "type": "string",
                                    "enum": [
                                        "tvContent",
                                        "thirdPartyContent"
                                    ]
                                },
                                "payload": {
                                    "description": "General property (applicable for different channels), although in the current model it only includes sub-properties for TV channels and thirdParties.",
                                    "anyOf": [
                                        {
                                            "$ref": "#/definitions/aura/bot/3.2.0/request/TvPayload"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/3.2.0/request/ThirdPartyPayload"
                                        },
                                        {
                                            "type": "object"
                                        }
                                    ]
                                }
                            },
                            "required": [
                                "type",
                                "payload"
                            ],
                            "title": "Element"
                        },
                        "TvPayload": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "contentId": {
                                    "description": "Content identifier.For live content, equivalent to show_id in Spain and schedule_id in GVP platform.",
                                    "type": "string"
                                },
                                "vodAssociated": {
                                    "description": "'true', if the content is available on Video on Demand; 'false' for all other content types.",
                                    "type": "boolean"
                                },
                                "resumeTime": {
                                    "description": "Time in seconds already watched by the user.",
                                    "type": "integer"
                                },
                                "catalogType": {
                                    "description": "Type of content being played. Possible values are: 'live' for broadcasted content; 'vod' for video on demmand; '17d' for last 7 days; 'record' for recordings. ",
                                    "type": "string",
                                    "enum": [
                                        "live",
                                        "vod",
                                        "l7d",
                                        "record"
                                    ]
                                },
                                "liveProgramId": {
                                    "description": "This property includes an identifier of the airing of the show the Telefónica customer is watching. Only for U7D, live and recordings. Equivalent to CRID_id in Spain and program_id in GVP platform.",
                                    "type": "string"
                                },
                                "season": {
                                    "description": "Season number for recurrent content.",
                                    "type": "integer"
                                },
                                "episode": {
                                    "description": "Episode number for recurrent content.",
                                    "type": "integer"
                                },
                                "title": {
                                    "description": "Content title (title of the movie or of the specific episode)",
                                    "type": "string"
                                },
                                "focus": {
                                    "description": "'true', if the visual element is focused; 'false' if not.",
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "contentId",
                                "catalogType"
                            ],
                            "title": "TvPayload"
                        },
                        "ThirdPartyPayload": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "thirdPartyId": {
                                    "description": "Identifier of the application or third party to which the content belongs.",
                                    "type": "string"
                                },
                                "thirdPartyName": {
                                    "description": "Name of the application or third party to which the content belongs.",
                                    "type": "string"
                                },
                                "contentId": {
                                    "description": "Content identifier.",
                                    "type": "string"
                                },
                                "catalogType": {
                                    "description": "Type of content being played. Possible values are: 'live' for broadcasted content; 'vod' for video on demmand; '17d' for last 7 days; 'record' for recordings.",
                                    "type": "string",
                                    "enum": [
                                        "live",
                                        "vod",
                                        "l7d",
                                        "record"
                                    ]
                                },
                                "title": {
                                    "description": "Content title (title of the movie or of the specific episode)",
                                    "type": "string"
                                },
                                "focus": {
                                    "description": "'true', if the visual element is focused; 'false' if not.",
                                    "type": "boolean"
                                },
                                "deeplink": {
                                    "description": "Content deeplink",
                                    "type": "string"
                                }
                            },
                            "title": "ThirdPartyPayload"
                        },
                        "ThirdParty": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "name": {
                                    "description": "This property includes a name of the ThirdParty for which it contains information.",
                                    "type": "string"
                                },
                                "data": {
                                    "description": "This property includes an open object where the channel can put all the information that is necessary to interact with the ThirdParty.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "name"
                            ],
                            "title": "ThirdParty"
                        },
                        "Playing": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "catalogType": {
                                    "description": "Type of content being played. Possible values are: 'live' for broadcasted content; 'vod' for video on demmand; '17d' for last 7 days; 'record' for recordings.",
                                    "type": "string",
                                    "enum": [
                                        "live",
                                        "vod",
                                        "l7d",
                                        "record"
                                    ]
                                },
                                "audioList": {
                                    "description": "This property includes an array whose values are 3-letters codes (ISO 639-2) stating the available audio language.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "currentAudioId": {
                                    "description": "This property states the audio language selected by the Telefónica client to play the associated content. The value of this property must be one of the keys included in the audioList property.",
                                    "type": "string"
                                },
                                "subtitlesList": {
                                    "description": "This property includes an array whose values are 3-letters codes (ISO 639-2) stating the available languages for subtitles.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "currentSubtitlesId": {
                                    "description": "This property states the subtitles language selected by the Telefónica client to play the associated content. The value of this property must be one of the keys included in the subtitlesList property. If no subtitles are selected, this property should not be included.",
                                    "type": "string"
                                },
                                "recordingAllowed": {
                                    "description": "This property indicates if the content can be recorded.The possible values of this property are: 'false', if the content cannot be recorded (unique possible value if 'type' is VoD); 'true', if the content can be recorded.",
                                    "type": "boolean"
                                },
                                "resumeTime": {
                                    "description": "Time in seconds already watched by the user.",
                                    "type": "integer"
                                },
                                "channelNumber": {
                                    "description": "In case the Telefónica customer is playing content on the TV device this property indicates the tuned dial the Telefónica customer is watching. Only for Live content.",
                                    "type": "string"
                                },
                                "contentId": {
                                    "description": "Content identifier.",
                                    "type": "string"
                                },
                                "channelId": {
                                    "description": "In case the Telefónica customer is playing content on an IPTV device, this property indicates the unique identifier of the channel the Telefónica customer is watching. Only for Live and recorded content.",
                                    "type": "string"
                                },
                                "liveProgramId": {
                                    "description": "Program id that allows to relate all the broadcasts of the same content. It is a Content ID.",
                                    "type": "string"
                                },
                                "startOverAllowed": {
                                    "description": "This property states if the associated content can be watched from the beginning or not. The possible values of this property are: 'false', if the content cannot be started again; 'true', if the content can be started again.",
                                    "type": "boolean"
                                },
                                "season": {
                                    "description": "Season number for recurrent content.",
                                    "type": "integer"
                                },
                                "episode": {
                                    "description": "Episode number for recurrent content.",
                                    "type": "integer"
                                },
                                "movedBackward": {
                                    "description": "This parameter is used to indicate that the user has moved the playback backwards, either with the 'view from the beginning' button or with the 'rewind' button. This parameter only makes sense when the user is watching a television channel, otherwise the value will be 'false'. It can take two values: 'false', if the user is watching a channel and has not moved its playback back; 'true' if he is watching a channel and has moved its playback backwards.",
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "catalogType",
                                "contentId"
                            ],
                            "title": "Playing"
                        },
                        "Channel": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "id": {
                                    "description": "This property includes a unique identifier in UUID format which uniquely identifies the channel in Aura. The UUID is the same for all OBs. This identifier must be provided by Aura Operations Team to the channel.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "interfaceLanguage": {
                                    "description": "This property includes a combination of ISO-3166 2-letters country codes and ISO 639-1 2-letter language code separated by a hyphen stating the language used by the Telefónica client to interact with the concrete Aura bot instance. For example, 'es-ES' for spanish used in Spain.",
                                    "type": "string"
                                },
                                "modality": {
                                    "description": "This property describes the way the Telefónica client used to interact with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "audio",
                                        "text",
                                        "form"
                                    ]
                                }
                            },
                            "required": [
                                "id",
                                "modality"
                            ],
                            "title": "Channel"
                        },
                        "Device": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "id": {
                                    "description": "This property includes a unique identifier of the device the Telefónica client used to interact with the Aura bot instance. This id must be already registered in the backends of the OB.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "This property states the type of device used by the Telefónica client used to interact with the Aura bot instance. The possible values should be aligned with the APIs backend to ensure that contents will be returned. Some values used nowadays are 'homebase', 'android.cell', 'remote', 'HB_TEF'",
                                    "type": "string"
                                },
                                "platform": {
                                    "description": "This property describes the specific platform the Telefónica client used to interact with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "home",
                                        "mobile",
                                        "other",
                                        "pc",
                                        "stb",
                                        "tablet",
                                        "tv"
                                    ]
                                },
                                "maxQuality": {
                                    "description": "Highest video quality of the device prepared to reproduce a content (physical media player device or external device). This field will have one of the following values: 'UHD_4K' for 4K content; 'HighDefinition' for HD content; 'StandardDefinicion' for SD content; 'LowDefinition' for LD content. These values are the same you can find in the 4P API for retrieving content (https://developers.baikalplatform.com/apis/video-contents/2.0.0/).",
                                    "type": "string",
                                    "enum": [
                                        "HighDefinition",
                                        "LowDefinition",
                                        "StandardDefinition",
                                        "UHD_4K"
                                    ]
                                },
                                "allowedCatalogTypes": {
                                    "type": "string",
                                    "description": "This property includes a comma-separated list of the catalog types that the device is able to play."
                                }
                            },
                            "required": [
                                "id",
                                "type"
                            ],
                            "title": "Device"
                        },
                        "Location": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "logical": {
                                    "description": "This property describes the location from where the Telefónica client interacts with the Aura bot instance.",
                                    "type": "string",
                                    "enum": [
                                        "home",
                                        "outside",
                                        "unknown"
                                    ]
                                },
                                "currentRegion": {
                                    "description": "[TV] This property indicates which is the TV demarcation where the user is at the time of the request. It is used to return to the user only those channels that she can see, based on this region. Property only available for TV channels.",
                                    "type": "string"
                                }
                            },
                            "title": "Location"
                        },
                        "TvUser": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "accountNumber": {
                                    "description": "This property includes an identifier uniquely identifying the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "ageRating": {
                                    "description": "This property includes the age rating code",
                                    "type": "string"
                                },
                                "childProfile": {
                                    "description": "This flag indicates if the profile for kids is enabled",
                                    "type": "boolean"
                                },
                                "productList": {
                                    "description": "This property includes a list of the products available in the active contract for the Telefónica client interacting with the Aura bot instance.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "profile": {
                                    "description": "This property describes the commercial offer chosen by the Telefónica client interacting with the Aura bot instance. This property only applies in the case of Spain for STB, Movistar Home and Movistar Plus channels. Some possible values for this property are: 'anonimo', 'basico', 'iptv', 'junior' in Spain; '58|TVOD' in GVP Platform.",
                                    "type": "string"
                                },
                                "purchaseList": {
                                    "description": "List with the content purchased by the user (tVOD).",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "STBList": {
                                    "description": "This property includes the list of STBs which belongs to the Telefónica client interacting with the Aura bot instance.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.2.0/request/STBType"
                                    }
                                },
                                "videoProfileName": {
                                    "description": "This property includes an identifier of the content profile the Telefónica client has selected to interact with the Aura bot instance.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "accountNumber",
                                "STBList"
                            ],
                            "title": "TvUser"
                        },
                        "STBType": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "id": {
                                    "description": "This property includes the device identifier of the STB.",
                                    "type": "string"
                                },
                                "model": {
                                    "description": "This property includes the device model of the STB.",
                                    "type": "string"
                                },
                                "prettyName": {
                                    "description": "This property includes a printable name of the STB device. This can be modified by the user using the STB UI.",
                                    "type": "string"
                                },
                                "remotePlayAllowed": {
                                    "description": "This property includes a boolean value (this is, true or false) describing if the STB device allows the possibility of playing content launched from a remote entity such as a mobile application.",
                                    "type": "boolean"
                                },
                                "remotePlayOn": {
                                    "description": "This property includes a boolean value (this is, true or false) describing if the STB device is on or off.",
                                    "type": "boolean"
                                },
                                "maxQuality": {
                                    "description": "Highest video quality of the device. This field will have one of the following values: 'UHD_4K' for 4K content; 'HighDefinition' for HD content; 'StandardDefinition' for SD content; 'LowDefinition' for LD content. These values are the same you can find in the 4P API for retrieving contents (https://developers.baikalplatform.com/apis/video-contents/2.0.0/).",
                                    "type": "string",
                                    "enum": [
                                        "HighDefinition",
                                        "LowDefinition",
                                        "StandardDefinition",
                                        "UHD_4K"
                                    ]
                                }
                            },
                            "required": [
                                "id",
                                "model",
                                "maxQuality"
                            ],
                            "title": "STBType"
                        },
                        "LivingApp": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "id": {
                                    "description": "[LA] This property includes an identifier uniquely identifying (UUID) the Living App in Aura.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "description": "[LA] This property includes a semantic identifier uniquely identifying the Living App in Aura.",
                                    "type": "string"
                                },
                                "prefix": {
                                    "description": "[LA] This property includes the short name associated to the Living App",
                                    "type": "string"
                                },
                                "sessionId": {
                                    "description": "[LA] This property includes an identifier uniquely identifying the session associated to the Living App in Aura. The  sessionId property must be sent if it was previously received in the start-living-app event response message.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "id",
                                "name",
                                "prefix",
                                "sessionId"
                            ],
                            "title": "LivingApp"
                        },
                        "AuraCommand": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "type": {
                                    "description": "Type of Aura command sent on behalf of the Telefónica client interacting with the Aura bot instance. The possible values of this property are:\n -'intent': This type of Aura command is associated to sending an already known user intention.\n - 'suggestion': This type of Aura command is dedicated to send the suggestions provided by Aura Bot. The command must be returned as it was sent, without any change.\n - 'notification': this type of Aura command is associated to an intent generated by a notification sent by Aura Notifications System.\n - 'operation': this type of Aura command is associated to intents which need an already running dialog context in Aura. It is something like a sub-dialog within a main one.\n - 'text': type of Aura command intended for setting a given text in the value of the command. The result will be the same as setting the string as the text of the request.\n - 'event': this Aura command contains an event that happened in the channel and must be informed to Aura bot, so it can be handled properly: stored in the context or in Kpis, for example.",
                                    "type": "string",
                                    "enum": [
                                        "intent",
                                        "suggestion",
                                        "notification",
                                        "operation",
                                        "text",
                                        "event"
                                    ]
                                },
                                "value": {
                                    "description": "This property includes the data needed to execute the command. Its content depends on the type of Aura command.",
                                    "anyOf": [
                                        {
                                            "$ref": "#/definitions/aura/bot/3.2.0/request/SuggestionValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/3.2.0/request/NotificationValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/3.2.0/request/EventValue"
                                        },
                                        {
                                            "type": "string"
                                        }
                                    ]
                                },
                                "utm": {
                                    "description": "It shows the exact interface element that was used by the user to launch the auraCommand.",
                                    "$ref": "#/definitions/aura/bot/3.2.0/request/Utm"
                                }
                            },
                            "required": [
                                "type",
                                "value"
                            ],
                            "title": "AuraCommand",
                            "allOf": [
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "pattern": "intent|suggestion|operation"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/3.2.0/request/SuggestionValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "notification"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/3.2.0/request/NotificationValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "text"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "event"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/3.2.0/request/EventValue"
                                            }
                                        }
                                    }
                                }
                            ]
                        },
                        "SuggestionValue": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference which will determine the Aura dialog to execute. The format of this property is: intent.<libraryId>.<intentId>.In case the prefix intent. is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: 'type':  this property includes a string stating the type of entity; 'entity': this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.2.0/request/Entity"
                                    }
                                }
                            },
                            "required": [
                                "intent"
                            ],
                            "title": "SuggestionValue"
                        },
                        "NotificationValue": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "action": {
                                    "description": "This property includes the Aura intention reference, that informs which dialog is executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>. As with the rest of intents, the Aura bot instance will add by default the prefix 'intent.' to resolve it.",
                                    "type": "string"
                                },
                                "notificationData": {
                                    "description": "This property includes detailed information about the notification being sent to the Telefónica client. The data sent will let Aura predict unusual behaviour in clients billing, balance or data consumption. Depending on the action, the data included in this property will be one of the payloads defined in aura-insights-events API (https://developers.baikalplatform.com/apis/aura-bot-events/)",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "action",
                                "notificationData"
                            ],
                            "title": "NotificationValue"
                        },
                        "EventValue": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference informing which dialog is executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>. As with the rest of intents, the Aura bot instance will add by default the prefix 'intent.' to resolve it.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: 'type':  this property includes a string stating the type of entity; 'entity': this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.2.0/request/Entity"
                                    }
                                },
                                "text": {
                                    "description": "User utterance.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "Event type: local-grammar.",
                                    "type": "string"
                                },
                                "payload": {
                                    "description": "Specific per event type.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "type"
                            ],
                            "title": "EventValue"
                        },
                        "Utm": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "source": {
                                    "description": "It identifies which site sent the traffic. Please, use the channel name.",
                                    "type": "string"
                                },
                                "medium": {
                                    "description": "It identifies what type of link was used, such as cost per click or email.",
                                    "type": "string"
                                },
                                "campaign": {
                                    "description": "It identifies a specific product promotion or strategic campaign.",
                                    "type": "string"
                                },
                                "term": {
                                    "description": "It identifies search terms.",
                                    "type": "string"
                                },
                                "content": {
                                    "description": "It identifies what was specifically clicked to bring the user to the site, such as a banner ad or a text link.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "source"
                            ],
                            "title": "Utm"
                        },
                        "Entity": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "canon": {
                                    "description": " This property includes the canonical form of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "endIndex": {
                                    "description": "The index at which this entity ends in the original user message.",
                                    "type": "number"
                                },
                                "entity": {
                                    "description": "This property includes the value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "label": {
                                    "description": "This property includes an internally used descriptive tag of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "score": {
                                    "description": "This property includes the accuracy (in per 1 units) of the recognized entity sent on behalf of the Telefónica client interacting with the Aura bot instance. In the case of Aura commands this value should be 1 since in this case fully recognized intentions are sent.",
                                    "type": "number"
                                },
                                "startIndex": {
                                    "description": "The index at which this entity starts in the original user message.",
                                    "type": "number"
                                },
                                "type": {
                                    "description": "This property includes the type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance. The format used by this property is the following one: ent.<entityType>",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "canon",
                                "entity",
                                "score",
                                "type"
                            ],
                            "title": "Entity"
                        },
                        "ImageSettings": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "graphicsWidth": {
                                    "description": "This property indicates the recommended width in pixels of the images the Aura bot instance should sent to the Telefónica client according to the communication means she is using to interact with Aura. The default value is 500.",
                                    "type": "integer"
                                },
                                "resolution": {
                                    "description": "This property indicates the recommended scaling factor the Aura bot instance should apply to the images sent to the Telefónica client. The possible values for this property are: 'mdpi': 1.0x; 'hdpi': 1.5x; 'xhdpi': 2.0x; 'xxhdpi': 3.0x; 'xxxhdpi': 4.0x.  The default value is 'mdpi'.",
                                    "type": "string",
                                    "enum": [
                                        "mdpi",
                                        "hdpi",
                                        "xhdpi",
                                        "xxhdpi",
                                        "xxxhdpi"
                                    ]
                                }
                            },
                            "title": "ImageSettings"
                        }
                    }
                }
            }
        }
    }
}

Docs:

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

JSON schema for channelData v3 response model

Description of the JSON schema for channelData v3 response model

General conventions

Properties corresponding to the response model can be general (applicable for all channels) or specific for TV channels. In order to identify the type(s) of each property, regarding the abovementioned classification, the following symbols will be used in the JSON schemas:

Types of properties	Tags in JSOn schemas
General property (applicable for all channels)	No tag in description
Specific property for TV channels Currently: Movistar Plus, Movistar Home, STB	Tag [TV] in description

The mandatory parameters are included in the field required of each property in the corresponding JSON files.

JSON schema for channelData v3 response model

{
    "$schema": "http://json-schema.org/schema#",
    "$id": "resource:/aura-models/channel-data/3.1.0/response/channeldata-3.1.0-response.schema#",
    "$ref": "#/definitions/aura/bot/3.1.0/response/ResponseChannelData",
    "$version": "3.1.0",
    "definitions": {
        "aura": {
            "bot": {
                "3.1.0": {
                    "response": {
                        "ResponseChannelData": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "intentResult": {
                                    "description": "Information about the intent and entities recognized by Aura.",
                                    "$ref": "#/definitions/aura/bot/3.1.0/response/IntentResult"
                                },
                                "actions": {
                                    "description": "Array of Actions, the actions available for this Aura response. It contains both general sub-properties and specific ones.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.1.0/response/Action"
                                    }
                                },
                                "status": {
                                    "description": "Object describing the status of the request sent to the Aura bot instance.",
                                    "$ref": "#/definitions/aura/bot/3.1.0/response/Status"
                                },
                                "version": {
                                    "description": "This property encodes the version of the Aura Request - Response Semantic Model being used, so the structural dependencies and semantics of the data provided can be properly managed (e.g, 0.1, 0.2, 0.3, 1.0.0, 2.0.0, 3, 4, etc). Semantic versioning 2.0.0. (https://semver.org/) is used.",
                                    "type": "string",
                                    "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
                                },
                                "correlator": {
                                    "description": "This property contains an UUID (https://en.wikipedia.org/wiki/Universally_unique_identifier) uniquely identifying the concrete request sent through the channel. This unique identifier is of great help when doing cross system analysis, as a way to correlate the actions executed by distinct elements of the whole system associated to the fulfilment of the same request.In case the correlator property is not provided, the Aura bot will generate one and pass it over in any interaction with any external component.",
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "payload": {
                                    "description": "Channel data payload information. This property can be used by an external component to aura-bot in order to send information for the enrichment of the request. Information is sent that does not correspond to the bot-framework communication model, but that aura-bot and certain dialogs use to complete processing. Currently it is used by components interacting with the bot through Aura bridge, but it could is used by any component.",
                                    "type": "object"
                                }
                            },
                            "title": "ChannelData"
                        },
                        "IntentResult": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "name": {
                                    "description": "Intent name (the intent recognized, processed and resolved by Aura), such as STB_ACTION.PLAY_ON_TV or MEDIA.SEARCH.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "Array of simplified entities detected by Aura (it may be empty)",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.1.0/response/SimplifyEntity"
                                    }
                                }
                            },
                            "required": [
                                "name"
                            ],
                            "title": "IntentResult"
                        },
                        "SimplifyEntity": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "entity": {
                                    "description": "This property includes the value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "This property includes the type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance. The format used by this property is the following one: ent.<entityType>",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "entity",
                                "type"
                            ],
                            "title": "SimplifyEntity"
                        },
                        "Action": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "name": {
                                    "description": "Action to be performed. Some values that this property can take are: 'CALL', 'SOUND'.",
                                    "type": "string"
                                },
                                "target": {
                                    "description": "Target for the action, such as 'stb'. If the action should be executed by the device used by the user to interact with Aura, the value should be 'channel'. The STB team should consider the value 'stb' and 'channel' indistinctly.",
                                    "type": "string"
                                },
                                "params": {
                                    "description": "An object with the required params for the action.",
                                    "oneOf": [
                                        {
                                            "type": "object"
                                        }
                                    ]
                                },
                                "postBack": {
                                    "description": "Action to be performed by the channel once the action is completed. Depending on the result, independent actions could be executed. This property may contain 2 possible exclusive properties: 'ok', containing auraCommand type properties; 'error', containing auraCommand type properties.",
                                    "$ref": "#/definitions/aura/bot/3.1.0/response/PostBack"
                                }
                            },
                            "required": [
                                "name",
                                "target"
                            ],
                            "title": "Action"
                        },
                        "PostBack": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "ok": {
                                    "description": "Contains the command to send to Aura if the actions finalized without errors.",
                                    "$ref": "#/definitions/aura/bot/3.1.0/response/AuraCommand"
                                },
                                "error": {
                                    "description": "Contains the command to send to Aura if the actions finalized with errors.",
                                    "$ref": "#/definitions/aura/bot/3.1.0/response/AuraCommand"
                                }
                            },
                            "title": "PostBack"
                        },
                        "AuraCommand": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "type": {
                                    "description": "Type of Aura command sent on behalf of the Telefónica client interacting with the Aura bot instance. The possible values of this property are:\n - 'intent': This type of Aura command is associated to sending an already known user intention.\n - 'suggestion': This type of Aura command is dedicated to send the suggestions provided by Aura Bot. The command must be returned as it was sent, without any change.\n - 'notification': this type of Aura command is associated to an intent generated by a notification sent by Aura Notifications System.\n - 'operation': this type of Aura command is associated to intents which need an already running dialog context in Aura. It is something like a sub-dialog within a main one.\n - 'text': this type of Aura command is intended for setting a given text in the value of the command. The result will be the same as setting the string as the text of the request.\n - 'event': this type of Aura command contains an event that happened in the channel and that must be informed to Aura bot so it can be handled properly, stored  in the context or kpis, for example.",
                                    "type": "string",
                                    "enum": [
                                        "intent",
                                        "suggestion",
                                        "notification",
                                        "operation",
                                        "text",
                                        "event"
                                    ]
                                },
                                "value": {
                                    "description": "This property includes the data needed to execute the command. Its content depends on the type of Aura command.",
                                    "anyOf": [
                                        {
                                            "$ref": "#/definitions/aura/bot/3.1.0/response/SuggestionValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/3.1.0/response/NotificationValue"
                                        },
                                        {
                                            "$ref": "#/definitions/aura/bot/3.1.0/response/EventValue"
                                        },
                                        {
                                            "type": "string"
                                        }
                                    ]
                                },
                                "utm": {
                                    "description": "It shows the exact interface element that was used by the user to launch the auraCommand.",
                                    "$ref": "#/definitions/aura/bot/3.1.0/response/Utm"
                                }
                            },
                            "required": [
                                "type",
                                "value"
                            ],
                            "title": "AuraCommand",
                            "allOf": [
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "pattern": "intent|suggestion|operation"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/3.1.0/response/SuggestionValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "notification"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/3.1.0/response/NotificationValue"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "text"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                },
                                {
                                    "if": {
                                        "properties": {
                                            "type": {
                                                "const": "event"
                                            }
                                        }
                                    },
                                    "then": {
                                        "properties": {
                                            "value": {
                                                "$ref": "#/definitions/aura/bot/3.1.0/response/EventValue"
                                            }
                                        }
                                    }
                                }
                            ]
                        },
                        "SuggestionValue": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference which will determine the Aura dialog to execute. The format of this property is: intent.<libraryId>.<intentId>. In case the prefix 'intent.' is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: 'type':  this property includes a string stating the type of entity; 'entity': this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.1.0/response/Entity"
                                    }
                                }
                            },
                            "required": [
                                "intent"
                            ],
                            "title": "SuggestionValue"
                        },
                        "NotificationValue": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "action": {
                                    "description": "This property includes the Aura intention reference informing of which dialog is executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>. As with the rest of intents, the Aura bot instance will add by default the prefix 'intent.' to resolve it.",
                                    "type": "string"
                                },
                                "notificationData": {
                                    "description": "This property includes detailed information about the notification being sent to the Telefónica client. The data sent will let Aura predict unusual behavior in clients billing, balance or data consumption. Depending on the action, the data included in this property will be one of the payloads defined in the aura-insights-events API (https://developers.baikalplatform.com/apis/aura-bot-events/)",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "action",
                                "notificationData"
                            ],
                            "title": "NotificationValue"
                        },
                        "EventValue": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "intent": {
                                    "description": "This property includes the Aura intention reference informing which dialog is executed to accomplish the Telefónica client intent. The format of this property is: <libraryId>.<intentId>. In case the prefix 'intent.' is not included in the value of this property, it will be included by default.",
                                    "type": "string"
                                },
                                "entities": {
                                    "description": "This property includes an array of additional information the Aura bot instance needs to properly accomplish the intent of the Telefónica client. Every entity is a JSON object including 2 properties: 'type':  this property includes a string stating the type of entity; 'entity': this property includes a string stating the value of the entity.",
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/aura/bot/3.1.0/response/Entity"
                                    }
                                },
                                "text": {
                                    "description": "User utterance.",
                                    "type": "string"
                                },
                                "type": {
                                    "description": "Event type: local-grammar.",
                                    "type": "string"
                                },
                                "payload": {
                                    "description": "Specific per event type.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "type"
                            ],
                            "title": "EventValue"
                        },
                        "Utm": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "source": {
                                    "description": "It identifies which site sent the traffic. Please, use the channel name.",
                                    "type": "string"
                                },
                                "medium": {
                                    "description": "It identifies what type of link was used, such as cost per click or email.",
                                    "type": "string"
                                },
                                "campaign": {
                                    "description": "It identifies a specific product promotion or strategic campaign.",
                                    "type": "string"
                                },
                                "term": {
                                    "description": "It identifies search terms.",
                                    "type": "string"
                                },
                                "content": {
                                    "description": "It identifies what was specifically clicked to bring the user to the site, such as a banner ad or a text link.",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "source"
                            ],
                            "title": "Utm"
                        },
                        "Entity": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "canon": {
                                    "description": " This property includes the canonical form of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "endIndex": {
                                    "description": "Index at which this entity ends in the original user message.",
                                    "type": "number"
                                },
                                "entity": {
                                    "description": "This property includes the value of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "label": {
                                    "description": "This property includes an internally used descriptive tag of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance.",
                                    "type": "string"
                                },
                                "score": {
                                    "description": "This property includes the accuracy (in per 1 units) of the recognized entity sent on behalf of the Telefónica client interacting with the Aura bot instance. In the case of Aura commands this value should be 1 since in this case fully recognized intentions are sent.",
                                    "type": "number"
                                },
                                "startIndex": {
                                    "description": "The index at which this entity starts in the original user message.",
                                    "type": "number"
                                },
                                "type": {
                                    "description": "This property includes the type of the entity sent on behalf of the Telefónica client interacting with the Aura bot instance. The format used by this property is the following one: ent.<entityType>",
                                    "type": "string"
                                }
                            },
                            "required": [
                                "canon",
                                "entity",
                                "score",
                                "type"
                            ],
                            "title": "Entity"
                        },
                        "Status": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                                "code": {
                                    "description": "Internal Aura status code. Get more info in @telefonica/aura-models, within the path src/channel-data/status/aura-status-codes-v3.ts",
                                    "type": "string"
                                },
                                "message": {
                                    "description": "Descriptive text with additional information.",
                                    "type": "string"
                                },
                                "params": {
                                    "description": "Extended information about the status, it may be empty or not sent. If exists, it will contain extra params needed to handle programmatically the status properly.",
                                    "type": "object"
                                }
                            },
                            "required": [
                                "code",
                                "message"
                            ],
                            "title": "Status"
                        }
                    }
                }
            }
        }
    }
}

Docs:

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

Aura request-response semantic model

This section describes the Aura request-response semantic model, which makes it possible for external software components, application and services to speak a language Aura can understand using the Direct Line API

Aura Virtual Assistant component

Introduction

The Direct Line API provides the connectivity between any external software component, service, channel or application and Aura skills.

Anyhow, having a connection means is typically not enough, as a proper understanding and semantics are needed between the communicating parties regarding the data being intercommunicated. In order to improve the communication of Aura with services or channels being integrated into the Microsoft Azure Bot Service and Bot Framework, two concepts come into play:

Activities
Fixed JSON format. This fixed JSON format includes a JSON property called channelData, which channel developers and integrators can use to encode channel-specific data in JSON format and its corresponding semantics.

In this framework, we introduce the so-called Aura Request - Response Semantic Model. This semantic model makes it possible for external software components, application and services to speak a language Aura can understand using the DirectLine API.

Currently, this semantic model is used both for the communication of channels with aura-groot and for the communication of aura-groot with skills in two Aura communication protocols:

Within the Aura Request - Response Semantic Model, two key properties will be fully described throughout these documents:

The general-purpose channel-specific channelData property is the one used by Aura to define the model. When a message is sent from a channel, part of that message is specific to the channel/service and it allows aura-groot and skills to communicate correctly with it.
The payload property can be used by an external component to facilitate the sharing of information between the channels, aura-groot and the skills in order add extra information associated with the channel and, consequently, enrich the request.

Versioning

Aura supports different versions of the Aura Request - Response Semantic Model.

channelData v1

In older Aura Platform releases, the default version was version 1, so some channels did not send the version of the channelData and aura-bot handled their requests as version 1.0.0.

There is an exception: in release Aerosmith, aura-bot included Living Apps handling as a platform feature.

➡️ Access to channelData v1 documentation

channelData v2

Afterwards, version 2 was created to extend the channelData property with new fields, such as actions and status, that with the regular communications with the channels are not needed or, in the case of the actions, are solved by other ad-hoc means.

In Greenday (6.0.1) release, Aura included a WhatsApp connector, the so-named aura-bridge and also channelData version 2 was used to access and to use the extra features of actions and status.

In these Aura Platform releases until Iron Maiden, aura-bot included a lazy definition of the channelData model, so, in fact, it handled almost a different version per channel.

➡️ Access to channelData v2 documentation

channelData v3

From Iron Maiden (7.2.0) onwards, we introduce the so-called channelData normalized version (version 3), an enriched version of channelData with new fields that provide a complete schema definition. This will enforce all channels to use the very same schema to access aura-groot.

➡️ Access to channelData v3 documentation