Docs:

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

Set Top Box channel in Aura

Introduction to Set Top Box channel in Aura, architecture and key features. Description of how works the integration between the STB and Aura.

Related documents

Global video use cases

Introduction to Set Top Box channel in Aura

Television is currently one of the primary channels used by the customers of Telefónica’s brands across the countries. Indeed, Telefónica, as the owner of the channel, decides what is to be shown on it. The integration of Aura into the set-top-boxes (STB) of the countries streamlines access for end users, enabling them to explore the whole set of available TV features in each country.

Aura is available in the remote controller of the TV platforms
Aura provides natural language understanding for the user
Aura makes it easier to navigate through all the options of the graphical interface
Aura recognizes the main intentions of the users

Presently, Aura provides, among others, the functionalities listed below in STB:

Actions to be executed by the device: record a content, change language, go to the beginning, go to the end, etc.
Search in the TV content repository
Information about what is the user watching
Navigation through different sections of the interface
Small Talk (greetings, goodbyes, thank yous, swear words)

Regarding the integration between the STB and Aura, there are currently two different implementations, depending on the version of the channelData used by the channel, and the version of the TV API used:

STB channel in Spain, it is using channelData V1, with the legacy TV APIs.
STB channel in Brazil, it is using channelData V3, with the normalized TV APIs.

All use cases are being moved to channelData V3, that in the end, will be the only one available for the integration.

Architecture overview

This section is WIP and will be completed soon.

Overview of Aura - STB communication architecture

STB uses Microsoft DirectLine protocol to access Aura. Further details in Microsoft Bot Service.

Authentication in STB channels

STB uses Non-integrated authentication, i.e. it is responsible for authenticating its users and calling the proper method to store the authorization_id for the Aura user.

Aura responses to STB channel

ChannelData version 1

Although STB channel in Spain uses channelData version 1, it counts on some requirements that are more strict than the Aura request and response model definition.

Field `attachments`

attachments is optional for DirectLine activities, but it is mandatory for STB, i.e. they always send both customAuraContent and customDataAsAttachment. It should contain the list of TV contents or the suggestions returned by the use case; if the use case does not return TV contents nor suggestions, for instance it only returns a text, a special attachment is expected.

type is mandatory and must have a proper value. common for those use cases returning only texts or no action to be executed by the device.
action is also mandatory and must contain the action to be executed by the device. If no action is to be executed, then noAction should be passed.
data is also mandatory, it contains the result of the use the case. If no data is needed, then an empty string should be sent.
name is also mandatory and it must be AuraCustomData.

Examples

Aura’s response to STB with TV suggestions

[
    {
        "type": "Receive_Message",
        "activity": {
            "type": "message",
            "id": "Fdhko0UbZYn4ONV7HWsINn-eu|0000015",
            "timestamp": "2025-04-15T13:47:33.8091689Z",
            "channelId": "directline",
            "from": {
                "id": "BOT-aura-ap-four",
                "name": "BOT-aura-ap-four"
            },
            "conversation": {
                "id": "Fdhko0UbZYn4ONV7HWsINn-eu"
            },
            "text": "Hola, aquí estoy para ayudarte",
            "speak": "Hola, aquí estoy para ayudarte",
            "inputHint": "acceptingInput",
            "attachments": [
                {
                    "contentType": "application/vnd.microsoft.card.hero",
                    "content": {
                        "buttons": [
                            {
                                "type": "postBack",
                                "title": "Busca películas de comedia",
                                "value": {
                                    "name": "Busca películas de comedia",
                                    "text": "Película comedia",
                                    "type": "suggestion",
                                    "intent": "intent.tv.search",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_genre",
                                            "entity": "películas",
                                            "canon": "películas",
                                            "label": "CN",
                                            "score": 1
                                        },
                                        {
                                            "type": "ent.audiovisual_subgenre",
                                            "entity": "comedia",
                                            "canon": "humor",
                                            "label": "HU",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Quiero ver la película La ternura",
                                "value": {
                                    "name": "Quiero ver la película La ternura",
                                    "text": "Ver La ternura",
                                    "type": "suggestion",
                                    "intent": "intent.tv.search",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_film_title",
                                            "entity": "La ternura",
                                            "canon": "La ternura",
                                            "label": "",
                                            "score": 1
                                        },
                                        {
                                            "type": "ent.audiovisual_genre",
                                            "entity": "película",
                                            "canon": "películas",
                                            "label": "CN",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Películas en Fox",
                                "value": {
                                    "name": "Películas en Fox",
                                    "text": "Películas hoy Fox",
                                    "type": "suggestion",
                                    "intent": "intent.tv.content_get_info",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_channel",
                                            "entity": "Fox",
                                            "canon": "Fox",
                                            "label": "",
                                            "score": 1
                                        },
                                        {
                                            "type": "ent.audiovisual_genre",
                                            "entity": "Películas",
                                            "canon": "películas",
                                            "label": "CN",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Cuando es el partido del Madrid",
                                "value": {
                                    "name": "Cuando es el partido del Madrid",
                                    "text": "Partido del Real Madrid",
                                    "type": "suggestion",
                                    "intent": "intent.tv.question_time_loc",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_sports_team",
                                            "entity": "Real Madrid",
                                            "canon": "real madrid",
                                            "label": "",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Quiero ver Divinity",
                                "value": {
                                    "name": "Quiero ver Divinity",
                                    "text": "Ver Divinity",
                                    "type": "suggestion",
                                    "intent": "intent.tv.display",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_channel",
                                            "entity": "Divinity",
                                            "canon": "Divinity",
                                            "label": "",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Quiero quitar los subtítulos",
                                "value": {
                                    "name": "Quiero quitar los subtítulos",
                                    "text": "Desactivar subtítulos",
                                    "type": "suggestion",
                                    "intent": "intent.tv.subtitles_remove",
                                    "entities": [],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            }
                        ]
                    },
                    "name": "SUGGESTIONS"
                },
                {
                    "contentType": "application/json",
                    "content": {
                        "type": "common",
                        "action": "COMMON.GREETINGS",
                        "data": {},
                        "data_additional": {},
                        "status": {
                            "code": "200",
                            "message": "Success - General Code",
                            "info": {}
                        }
                    },
                    "name": "AuraCustomData"
                }
            ],
            "channelData": {
                "intent": {
                    "id": "intent.common.greetings",
                    "name": "intent.common.greetings",
                    "entities": []
                },
                "content": {
                    "text": "Hola, aquí estoy para ayudarte",
                    "speak": "Hola, aquí estoy para ayudarte",
                    "sound": "positive",
                    "actions": []
                },
                "dialogContext": [
                    {
                        "text": "Busca películas de comedia",
                        "value": {
                            "name": "Busca películas de comedia",
                            "text": "Película comedia",
                            "type": "suggestion",
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_genre",
                                    "entity": "películas",
                                    "canon": "películas",
                                    "label": "CN",
                                    "score": 1
                                },
                                {
                                    "type": "ent.audiovisual_subgenre",
                                    "entity": "comedia",
                                    "canon": "humor",
                                    "label": "HU",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Quiero ver la película La ternura",
                        "value": {
                            "name": "Quiero ver la película La ternura",
                            "text": "Ver La ternura",
                            "type": "suggestion",
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_film_title",
                                    "entity": "La ternura",
                                    "canon": "La ternura",
                                    "label": "",
                                    "score": 1
                                },
                                {
                                    "type": "ent.audiovisual_genre",
                                    "entity": "película",
                                    "canon": "películas",
                                    "label": "CN",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Películas en Fox",
                        "value": {
                            "name": "Películas en Fox",
                            "text": "Películas hoy Fox",
                            "type": "suggestion",
                            "intent": "intent.tv.content_get_info",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_channel",
                                    "entity": "Fox",
                                    "canon": "Fox",
                                    "label": "",
                                    "score": 1
                                },
                                {
                                    "type": "ent.audiovisual_genre",
                                    "entity": "Películas",
                                    "canon": "películas",
                                    "label": "CN",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Cuando es el partido del Madrid",
                        "value": {
                            "name": "Cuando es el partido del Madrid",
                            "text": "Partido del Real Madrid",
                            "type": "suggestion",
                            "intent": "intent.tv.question_time_loc",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_sports_team",
                                    "entity": "Real Madrid",
                                    "canon": "real madrid",
                                    "label": "",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Quiero ver Divinity",
                        "value": {
                            "name": "Quiero ver Divinity",
                            "text": "Ver Divinity",
                            "type": "suggestion",
                            "intent": "intent.tv.display",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_channel",
                                    "entity": "Divinity",
                                    "canon": "Divinity",
                                    "label": "",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Quiero quitar los subtítulos",
                        "value": {
                            "name": "Quiero quitar los subtítulos",
                            "text": "Desactivar subtítulos",
                            "type": "suggestion",
                            "intent": "intent.tv.subtitles_remove",
                            "entities": [],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    }
                ],
                "fullScreen": false,
                "version": "1.0.0",
                "hasMoreMessages": false,
                "correlator": "084e5b86-9bc2-4f38-b7ae-21b34b46600f"
            },
            "replyToId": "Fdhko0UbZYn4ONV7HWsINn-eu|0000014"
        }
    }
]

Aura’s response to STB only with text

[
    {
        "type": "Receive_Message",
        "activity": {
            "type": "message",
            "id": "Fdhko0UbZYn4ONV7HWsINn-eu|0000009",
            "timestamp": "2025-04-15T13:36:35.5206701Z",
            "channelId": "directline",
            "from": {
                "id": "BOT-aura-ap-four",
                "name": "BOT-aura-ap-four"
            },
            "conversation": {
                "id": "Fdhko0UbZYn4ONV7HWsINn-eu"
            },
            "text": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
            "speak": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
            "inputHint": "acceptingInput",
            "attachments": [
                {
                    "contentType": "application/json",
                    "content": {
                        "type": "common",
                        "action": "noAction",
                        "data": {},
                        "data_additional": {},
                        "status": {
                            "code": "200",
                            "message": "Success - General Code",
                            "info": {}
                        }
                    },
                    "name": "AuraCustomData"
                }
            ],
            "channelData": {
                "intent": {
                    "id": "intent.tv.custom_recommendation",
                    "name": "intent.tv.custom_recommendation",
                    "entities": []
                },
                "content": {
                    "text": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
                    "speak": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
                    "sound": "positive",
                    "actions": []
                },
                "dialogContext": [],
                "fullScreen": false,
                "version": "1.0.0",
                "hasMoreMessages": false,
                "correlator": "ce12e579-76ad-4a75-8f98-7c6bae8260ca"
            },
            "replyToId": "Fdhko0UbZYn4ONV7HWsINn-eu|0000008"
        }
    }
]

Aura – stb