Categories:
channelData v1
Specification for channelData v1 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 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"
}
}
}
}
}
}
}
Last modified June 18, 2025: feat: Documentation improvement for Quotsa release #AURA-29739 [RTM] (f401ed2f)