Gracias por tu visita. Esta página solo está disponible en inglés.

GetDisplayableItems Directives (VSK MM)

When users make utterances to find content or try to access the content provider landing page, the VideoContentProvider API sends a GetDisplayableItems directive to your Lambda.

The following diagram shows the expected Alexa directive and Lambda response;

GetDisplayableItems Directive and Lambda GetDisplayableItemsResponse

Utterances for GetDisplayableItems

Alexa sends a GetDisplayableItems directive to your Lambda when users say the following utterances.

Feature Sample Utterances Expected Response
Search for <title>

Search for Breaking Bad

Find The Big Bang Theory

Suche nach <title>

Nach <title> suchen

cherches breaking bad

trouves breaking bad

cherches breaking bad

trouves breaking bad

cerca breaking bad

<House, The Office, Sneaky Pete>

busca breaking bad

busca breaking bad

búscame breaking bad

{title} を探して

{title} を検索して

procurar por {title}

buscar por {title}

{title} search करो

{title} ke liye search करो

A list of matches for the title is presented to the user.

Search by Media Type

Search movies

Suche nach <type>

<filme, videos, film>

cherches des films

trouves des films

cherches des films

trouves des films

cerca dei film

busca películas

busca películas

busca pelís

{media type} を探して

{media type} を検索して

procurar por filmes

buscar por filmes

{media type} search करो

{media type} ke liye search करो

A list of matches for the desired media type is presented to the user.

Search by Actor

Search for sean connery

Search for sean connery movies

Suche nach <actor>

<Ann Blyth, Axel Deller, John Oliver>

cherches sean connery

trouves sean connery

cherches sean connery

trouves sean connery

cerca sean connery

<Gianni Franco, Sonia Scotti, Stefano Sani>

busca sean connery

busca sean connery

busca a sean connery

{actor} を探して

{actor} を検索して

procurar por {actor}

buscar por {actor}

{actor name} search करो

{actor name} ke liye search करो

A list of matches featuring the actor is presented to the user.

Search <title> with season number

Search breaking bad season two

Suche nach <title> Staffel <number>

Suche nach der <number>. Staffel von <title> <Breaking Bad>

cherches la saison 2 de breaking bad

cherches la deuxième saison de breaking bad

cherches la saison 2 de breaking bad

cherches la deuxième saison de breaking bad

cerca la seconda stagione di breaking bad

cerca la stagione due di breaking bad

busca la temporada 2 de breaking bad

busca la segunda temporada de breaking bad

busca la temporada 2 de breaking bad

busca la segunda temporada de breaking bad

{title} シーズン{season number} を探して

{title} シーズン{season number} を探して

procurar a {ordinal number} temporada de {title}

procure a {ordinal number} temporada de {title}

{title} season two search करो

{title} season two ढूंढो

All episodes for the matching season are presented to the user.

Search <title> with episode number

Search for breaking bad episode five

Suche nach <title> Folge <number>

Suche nach <title> Episode <number>

cherches l' épisode 5 de breaking bad

cherches le cinquième épisode de breaking bad

cherches l' épisode 5 de breaking bad

cherches le cinquième épisode de breaking bad

cerca il quinto episodio di breaking bad

cerca l'episodio cinque di breaking bad

busca el episodio 5 de breaking bad

busca el capítulo 5 de breaking bad

busca el episodio 5 de breaking bad

busca el capítulo 5 de breaking bad

{title} エピソード{episode number} を探して

{title} エピソード{episode number} を探して

procurar o {ordinal number} episódio de {title}

procure o {ordinal number} episódio de {title}

{title} episode five search करो

{title} fifth episode ढूंढो

A list of available episodes within the season the user recently watched appears. For example, if the user's viewing progress is within Season 2, a list of episodes from Season 2 appears.

Search <title> with season and episode number

Search for breaking bad season two episode five

Suche nach <title> Staffel <season number> Folge <episode number>

Suche nach <title> Staffel <season number> Episode <episode number>

cherches l' épisode 5 de la saison 2 de breaking bad

cherches l' épisode 5 de la deuxième saison de breaking bad

cherches l' épisode 5 de la saison 2 de breaking bad

cherches l' épisode 5 de la deuxième saison de breaking bad

cerca il quinto episodio della stagione due di breaking bad

cerca l'episodio cinque della stagione due di breaking bad

busca el episodio 5 de la temporada 2 de breaking bad

busca el episodio 5 de la segunda temporada de breaking bad

busca el episodio 5 de la temporada 2 de breaking bad

busca el episodio 5 de la segunda temporada de breaking bad

{title} シーズン{season number} エピソード{episode number} を探して

{title} シーズン{season number} エピソード{episode number} を探して

procurar o {ordinal number} episódio da {ordinal number} temporada de {title}

procure o {ordinal number} episódio da {ordinal number} temporada de {title}

{title} season two episode five search करो

{title} season two fifth episode ढूंढो

A list of available episodes for the season the user requested appears, including the episode the user specifically asked for.

Search by franchise <title>

Search for star trek

Suche nach <title>

Zeige mir <title>

cherches star trek

trouves star trek

cherches star trek

trouves star trek

cerca star trek

<Superman, cars, Scream>

busca star trek

busca star trek

búscame star trek

{franchise} を探して

{franchise} を探して

procurar por {title}

buscar por {title}

{franchise title} search करो

{franchise title} ढूंढो search {franchise title}

The user is presented with a list of matching results for the franchise.

Search by Character Name

Search for james bond

Suche nach <actor>

Suche nach einem Film mit <actor>

cherches james bond

trouves james bond

cherches james bond

trouves james bond

ccerca james bond

<Superman>

busca james bond

busca james bond

busca a james bond

{character} を探して

{character} を探して

procurar por {character name}

buscar por {character name}

{character name} की picture दिखाओ

{character name} की movie search करो

The user is presented with a list of matching results for media featuring the character name.

Search by director name

Search for quentin tarantino

Suche nach einem Film von <director>

Suche nach <director>

cherches quentin tarantino

trouves quentin tarantino

cherches xavier dolan

trouves xavier dolan

cerca quentin tarantino

busca quentin tarantino

busca quentin tarantino

busca a quentin tarantino

{director name}監督の{media type}を探して

{director name}監督の{media type}を探して

procurar por {director name}

buscar por {director name}

{director name} search करो

{director name} ke liye search करो

The user is presented with a list of matching results for media produced by the requested director.

Search by production company

Search for disney

Suche nach Filmen von <name>

Suche nach einem Film von <name>

cherches disney

trouves disney

cherches disney

cerca disney

busca disney

busca disney

búscame disney

{company} を探して

{company} を探して

procurar por {production company}

buscar por {production company}

{production company} की filmein search करो

{production company} की filmein दिखाओ

The user is presented with a list of matching results for media from the production company.

Search by genre name

Search for comedy

Search comedy movies with Tom Hanks.

Suche nach <genre>

Suche eine <genre>

cherches une comédie

trouves une comédie

cherches une comédie

trouves une comédie

cerca una commedia

<Commedia>

busca comedia

busca comedia

busca comedias

{genre} を探して

{genre} を探して

procurar por {genre name}

buscar por {genre name}

The user is presented with a list of matching results for media from the requested genre (personalized through an algorithm that selects recommended media for the user).

Search by sports team

Search seahawks

Suche nach <sports team>

<Erster. FC Heidenheim, Erster FC Heidenheim, Erster FC Kaiserslautern>

cherches les bleus

trouves les bleus

cherches les canadiens

trouves les canadiens

cerca juventus

<Aberdeen, ac milan>

busca el Madrid

busca el América

búscame el América

{sports team} を探して

{sports team} を探して

procurar por {sports team}

buscar por {sports team}

{sports team} ढूंढो

{sports team} की

The user is presented with a list of matching results for the sports team.

Search by sports type

Search for soccer

Suche nach <sports type>

cherches du foot/football

trouves du foot/football

cherches du hockey

cerca calcio

busca fútbol

busca fútbol

búscame fútbol

{sports type} を探して

{sports type} を探して

procurar por {sports type}

buscar por {sports type}

{sports type} ढूंढो

{sports type}

The user is presented with a list of matching results for the sports type (preferably based on recommendations for the user).

Search by sports league

Search for n. b. a. league

Suche nach <sports league>

<Erste Baseball Bundesliga, Zweite Baseball Bundesliga, Zweite Bundesliga>

cherches la n.b.a.

trouves la n.b.a.

cherches la l. n. h.

trouves la l. n. h.

cerca l'n.b.a.

cerca la n.b.a.

busca la n. b. a.

busca la n. b. a.

búscame la n. b. a.

{sports league} を探して

{sports league} を探して

procurar por {sports league}

buscar por {sports league}

{sports league} ढूंढो

{sports league} matches दिखाओ

The user is presented with a list of matching results for the sports league (preferably based on recommendations for the user).

Search by sports event

Search for soccer game

Suche nach <sports event>

Suche <sports event>

cherches un match de foot/football

trouves un match de foot/football

cherches un match de hockey

trouves un match de hockey

cerca una partita di calcio

cerca partite

busca partidos de fútbol

busca partidos de fútbol

búscame partidos de fútbol

{sports event} を探して

{sports event} を探して

procurar por {sports event}

buscar por {sports event}

{sports event} दिखाओ

{sports event} ढूंढो

The user is presented with a list of matching results for the sports event (preferably based on recommendations for the user).

Launch <partner> app

Launch Netflix app

Starte <partner app>

<partner app> starten

lances netflix

ouvres netflix

lances netflix

ouvres netflix

apri (l'app di) Netflix

avvia Netflix

abre Netflix

abre Netflix

{app} 開いて

{app} 見せて

Alexa, abrir o app/aplicativo do/da/de {partner}

Alexa, ir para o app/aplicativo do/da/de {partner}

launch {app}

{app} launch करो

The requested app launches and shows a list of available media to play. Multimodal devices have a homepage template that gets populated with media potentially grouped in different categories.

Launch special character title

Launch a. t. and t. u-verse app

Starte a, t, und t. u-verse

A. t. und t. u.verse starten

lances a. t. et t. u- verse

ouvres a. t. et t. u- verse

abre (la app de) Movistar + (plus)

abrir {special character title}

ir para {special character title}

Launch {special character title} app

Launch {special character title}

The requested app launches and shows a list of available media to play. Multimodal devices have a homepage template that gets populated with media potentially grouped in different categories.

Launch app

Launch app

App starten

Starte App

lances l' application

ouvres l' application

lances l'appli

ouvres l'appli

apri (l')app

avvia (l')app

abre (la) app

abre (la) app

アプリを開いて

アプリを起動して

abrir {app}

ir para {app}

launch app

app launch करो

The requested app launches and shows a list of available media to play. Multimodal devices have a homepage template that gets populated with media potentially grouped in different categories.

Handling GetDisplayableItems Directives

When users search for content using criteria like VideoName, ActorName, GenreName, etc., Alexa sends a GetDisplayableItems directive to retrieve content to display.

Your Lambda response (GetDisplayableItemsResponse) should contain basic identifying information about the content that matches the user’s search request. Your response should not contain additional metadata such as images, etc.

Note that Alexa supports non-title requests such as "Alexa, find a comedy on <video provider>" or "Alexa, find football on <video provider>." For these requests, the expectation is that you conduct a search within your catalog and return a list of titles that matches the search request. Leverage any personalization algorithms you may have to bias the result to the user.

If you cannot find any results matching the user's request and return zero results in your response, you receive a second GetDisplayableItems directive with the SortType = Recommended. You can then return a set of recommended videos to the user in your response. Alexa tells the user that there are no search results, but that Alexa recommends this content to the user.

{
   "type": "SORTTYPE",
   "value": "RECOMMENDED"
}

You can then return a set of recommended videos to the user in your response. Alexa tells the user that there are no search results, but that Alexa recommends this content to the user.

GetDisplayableItems Example

The following is an example of a GetDisplayableItems directive:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetDisplayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Video",
                    "value": "Manchester by the Sea",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "en-US",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}

GetDisplayableItems Example (Landing Page)

When a user opens the provider landing page, Alexa sends two GetDisplayableItems directives.

  • The first directive is to retrieve categories for the landing page by setting the itemType property to CATEGORY and including a sortType of RECOMMENDED.
  • The second directive obtains the featured video for the landing page where the directive sets the itemType to VIDEO instead.

After that, Alexa sends one GetDisplayableItemsMetadata call with a list combined of Category IDs and Video ID. The response includes metadata about the video as well as the categories.

The following shows an example of a GetDisplayableItems directive used for a landing page:

{
   "directive": {
       "header": {
           "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
           "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
           "name": "GetDisplayableItems",
           "namespace": "Alexa.VideoContentProvider",
           "payloadVersion": "3"
        },
       "endpoint": {
           "scope": {
               "type": "BearerToken",
               "token": "access-token-from-skill"
            },
           "endpointId": "videoDevice-001",
           "cookie": {

            }
        },
       "payload": {
           "entities": [
                {
                   "type": "SORTTYPE",
                   "value": "RECOMMENDED"
                }
            ],
           "itemType" : "VIDEO",
           "locale": "en-US",
           "minResultLimit": 1,
           "maxResultLimit": 1
        }
    }
}

itemType specifies the type of item to be searched. The values can be either VIDEO or CATEGORY.

Payload Descriptions

The following table defines the payload fields for GetDisplayableItems directives.

Payload Descriptions
Field Description Data Type
entities
required

A list of entity objects to search. The relationship between different entity types should usually be interpreted as an AND operation. For example, if the request contains {genreName = "Comedy," actorName ="Tom Hanks"}, it implies that the search result should contain Comedy movies/TV shows with Tom Hanks.

However, if the request contains multiple entities of the same type, such as {videoName = "Interstellar," VideoName = "Interstellar Wars"}, then you can consider this as an OR operation and can search for all the entities in the directive. If in doubt, assume that the top entity within the type (videoName in this case) is the most relevant.

Let's say you have another request with {mediaType = "MOVIE', genreName = "Comedy," actorName ="Tom Hanks," actorName = "Tom Hanks}. This is assuming that there are multiple actors named Tom Hanks. In such cases, you can search for movies with all the actors in the request and then filter based on the Comedy genre to return all the search results.

Alexa does not rank the entities today because Alexa does not have a way to know what the user wants to play when there are multiple matching entities.

entities with a type: Channel contain identifying data for a television channel. For example:

 {
  "type": "Channel",
  "value": "PBS",
  "externalIds": {
      "gracenote": "MV000000099001"
  },
  "entityMetadata": {
      "channelCallSign": "KBTC",
      "channelNumber": "123"
  }
} 

List
type

Entity types for video content. For information about video content entity types, see [Entity Types for Video Content](../video-skills-fire-tv-apps/entity-types-for-video-content.html). In addition to that list, Alexa Skills Kit has added the following types for multimodal devices: LISTTYPE, SORTTYPE.

LISTTYPE is populated when users wants to browse their Watchlist or Library. For example, utterances like "Show me my Watchlist" or "Show me my Video Library." LISTTYPE can have the following enum values:

  • WATCHLIST: For "Show me my Watchlist" — used to show videos the user has added to their watchlist.
  • LIBRARY: For "Show me my Video Library" — used to show videos that are in the users' library. Typically, these are the videos that have been purchased by the user.

SORTTYPE is used to give additional information about the request that should be used during the searches and how results need to be sorted. For example, for "Show me recommended movies," Alexa needs recommendations from the content provider. SORTTYPE can have the following enum value:

  • RECOMMENDED: This value is populated for utterances like "Show me recommended movies," or "Show me recommended action movies," etc.

Examples: MEDIATYPE, VIDEO, ACTOR, GENRE, FRANCHISE, SEASON, EPISODE

String
value
required

The value of the entity. For channels, the name of the channel.

Examples: Interstellar, PBS

String
itemType

itemType specifies the type of item to be searched. itemType is unique for GetDisplayableItems directives related to the landing page template. When a user opens your landing page (by saying "Alexa, open ACME video" or by saying "Video Home" and then selecting your video skill), Alexa sends two GetDisplayableItems directives:

  • The first GetDisplayableItems directive is to retrieve categories for the landing page by setting the itemType property to CATEGORY and including a sortType of RECOMMENDED.
  • The second GetDisplayableItems directive obtains the featured video for the landing page where the request sets the itemType to VIDEO instead.

After receiving your response (GetDisplayableItemsResponse) for both directives, Alexa sends one GetDisplayableItemsMetadata call with a list combined of Category IDs and Video ID. The response includes metadata about the video as well as the categories.

Example: VIDEO, CATEGORY

Enum
externalIds

A map of external identifiers for this entity; key is the provider, value is the id.

Examples: key = gracenote or gti, value = SH000000012

Object
Gracenote

The external Gracenote identifier.

Example: ST0000000666661

String
contentType
required

ContentType specifies the content type for the video that was returned in the search results. If you send a recorded movie or TV show, the contentType is set to RECORDING. If the result contains information about a live TV show, then the contentType is set to LIVE. If the result contains an on-demand content, then the contentType is set to ON_DEMAND.

ContentType is also used to render a prompt to the user. For example, if the contentType is LIVE, Alexa renders a prompt such as, "Here's the Academy Awards now airing on CBS, from your DVR." If the contentType is RECORDING, Alexa renders a prompt such as, "Here's the Academy Awards from your DVR."

Examples: RECORDING, LIVE, ON_DEMAND

Enum
locale
required

The locale for the user that should be used to get displayable information for the search results. A locale in the same format specified for languages in in the Network Working Group Best Current Practice 47 (BCP-47). If you receive an unrecognized locale, default to en-US.

Examples: en-US, en-GB, de-DE

String
minResultLimit
required

The minimum number of results to return in this call for which a pageToken is accepted. If you return less than the minResultLimit field along with a pageToken to fetch more results, then Alexa does not consider the pageToken to fetch the new items and only displays whatever Alexa received.

For a pageToken to be considered for fetching more results, the number of items have to match at least the value in minResultLimit. However, the number of items can be more than minResultLimit up to a max of maxResultLimit. If the number of items is more than the maxResultLimit, Alexa discards the items after the maxResultLimit.

Example: 8

Integer
maxResultLimit
required

A limit to the maximum number of results to return. See description of minResultLimit field for more details.

Example: 25

Integer
timeWindow

Provides the start and end times that the request should act on. This is usually used for Live TV or Recording only and not for On Demand content. Generally, if the time window is available and can be used to filter the results, you should use it.

For providers that only search for On Demand content, the time window field is usually be set to null and can be ignored.

For Live TV or Recording, if the user specifies the time window, for example, "Search for TV shows between 4 and 5 pm," or "Find TV shows recorded last week," then you should filter the results based on the start and end times whenever available.

Depending on the capabilities, either both the fields — start and end — can be present, or any one field can be present. For example for "Search TV shows between 4 and 5 pm," both the fields are present. For "Show me TV shows starting at 5 pm," only the start field is populated while end is null.

Object containing start and end times.
end

The end time of the time window.

Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z

A string in ISO 8601 format.
start

The start time of the time window.

Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z

A string in ISO 8601 format.

Response Example

After receiving a GetDisplayableItems directive, your Lambda should send a GetDisplayableItemsResponse. The response should contain list of id values of the items to display on the device.

The following is an example of a GetDisplayableItemsResponse that your Lambda should send back to Alexa.

{
"directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetDisplayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [{
                    "mediaIdentifier": {
                        "id": "tt1254207"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt0807840"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt7993892"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt4957236"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "tt2285752"
                    }
                }
            ]
        }
    }
};

Payload Descriptions

The following table describes the payload fields in your GetDisplayableItemsResponse.

Payload Descriptions
Field Description Data Type
nextToken

Token to fetch the next set of results. An opaque string sent by the provider which is passed back in subsequent search requests.

String
mediaItems
required

A list of mediaIdentifiers for the videos that are shown as search results on the screen.

List
mediaIdentifier
required

Identifier for the mediaItem.

Object
id
required

An identifier for the video item that is used to fetch any display or playback related metadata information on subsequent calls to GetDisplayableItemsMetadata or GetPlayableItemsMetadata. This identifier is opaque to Alexa and is just used as-is when querying for metadata information.

String

Declaring Capability Support for this Interface

To indicate that your video skill supports the Alexa.RemoteVideoPlayer interface, you must indicate support for it in your response to the Discover directive sent through the Alexa.Discovery interface. More details are provided in Alexa.Discovery.