Developer Console
Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

GetDisplayableItems Directives (VSK Echo Show)

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 Version
Search for <title>

Search for breaking bad

such nach? <VideoName> such/zeig/find film? <VideoName> auf <AppName>

zeig mir film? <VideoName> auf <DeviceBrand>

such trailer von <VideoName>

trouve / cherche / montre <VideoName> sur <AppName>

trouve / cherche / montre <VideoName> sur <AppName>

trova / cerca / mostra / dammi + VideoName (+ da/su ServiceName)?

muestra juego de tronos

enséña me el efecto mariposa

<VideoName>を探して<VideoName>を<AppName>で探して

procurar/buscar/mostrar <VideoName> no/na <AppName>

 

<VideoName> खोजो/ढूँढो <AppName> पे/पर/में <VideoName> दिखा/खोज दो मुझे <VideoName> दिखाओ/खोजो/ढूँढो मुझे <AppName> पे/पर/में <VideoName> दिखाओ/खोजो/ढूँढो मुझे <VideoName> को <AppName> पे

पर में दिखाओ/खोजो/ढूँढो खोजो <VideoName>

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

1.0

Search by media type

Search movies

find <MediaType>

such/zeig/empfiehl <MediaType>

Cherche <mediatype>

recherche <mediatype>

cherche <mediatype>

cerca <mediatype>

trova mi un <mediatye>

busca películas

enséña me las películas

busca películas en netflix

<MediaType>を探して

<AppName>で<MediaType>を探して

<ChannelName>を検索

procurar <MediaType>

<VideoName> movie दिखाओ/ढूँढो

<AppName> पे/पर/में <MediaType> को खोजो

<ChannelName> को खोजो/ढूँढो

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

1.0

Search by Actor

Search for sean connery

Search for sean connery movies

such <ActorNameName> filme

zeig filme mit <ActorNameName>

cherche des films avec <ActorName>

recherche des films avec <ActorName>

cherche des films avec <ActorName>

cerca film con <ActorName>

trova un film con <ActorName>

busca películas con antonio banderas

<ActorNameName>が出ている<MediaType>を探して

procurar por <ActorName>

<ActorName> के/का/की/वाला movies दिखाओ/ढूँढो

<ActorName> के/का/की/वाला <GenreName> movies दिखाओ/खोजो/ढूँढो

<ActorName> के/का/की/वाला <GenreName> movie <VideoName> दिखाओ/खोजो/ढूँढो

दिखाओ/खोजो <ActorName> के/का/की/वाला <GenreName> movies

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

1.0

Search <title> with season number

Search breaking bad season two

spiel <VideoName> <Season> <Season_Numer>

spiel <VideoName>

<Season> <Season_Numer> auf <AppName>

cherche la saison <number> de <title>

recherche la saison <number> de <title>

cherche la saison <number> de <title>

cerca la stagione due di <VideoName>

trova la stagione due di <VideoName>

enséña me la segunda temporada de friends

procurar <VideoName> temporada <SeasonNumber>

breaking bad season दो ढूँढ़ो/ढूँढ़ना/खोजो/खोजना/search करना

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

1.0

Search <title> with episode number

Search for breaking bad episode five

spiel die <Episode_Number> <Episode> von <VideoName>

spiel <VideoName> <Episode_Number>

spiel von <VideoName> <Episode> <Episode_Number>

cherche l'épisode <number> de <title>

recherche la saison <number> de <title>

cherche la saison <number> de <title>

cerca <VideoName> Episodio cinque

trova <VideoName> Episodio cinque

busca el capítulo final de los serrano*

procurar por <title> episódio <EpisodeNumber>

breaking bad episode पाँच के लिए ढूँढ़ो/ढूँढ़ना/खोजो/खोजना/search करना

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.

1.0

Search <title> with season and episode number

Search for breaking bad season two episode five

spiel <Season> <Season_Numer> <Episode> <Episode_Number> von <VideoName>

spiel <VideoName> <Season> <Season_Numer> <Episode> <Episode_Number>

spiel die <VideoName> <Season> <Season_Numer> <Episode>

<Episode_Number> auf <AppName> ab

cherche la saison <SeasonNumber> de <VideoName>

cherche l'épisode <EpisodeNumber> de <VideoName>

cherche l'épisode <EpisodeNumber> de la saison <SeasonNumber> de <VideoName>

cherche la saison <SeasonNumber> de <VideoName>

cherche l'épisode <EpisodeNumber> de <VideoName>

cherche l'épisode <EpisodeNumber> de la saison <SeasonNumber> de <VideoName>

recherche/cherche la saison <SeasonNumber> de <VideoName>

recherche/cherchel'épisode <EpisodeNumber> de <VideoName>

recherche/cherchel'épisode <EpisodeNumber> de la saison <SeasonNumber> de <VideoName>

recherche/cherchela saison <SeasonNumber> de <VideoName>

recherche/cherchel'épisode <EpisodeNumber> de <VideoName>

recherche/cherchel'épisode <EpisodeNumber> de la saison <SeasonNumber> de <VideoName>

cerca <VideoName> episodio <EpisodeNumber>

trova <VideoName> episodio <EpisodeNumber>

cerca <VideoName> stagione <SeasonNumber>

trova <VideoName> stagione <SeasonNumber>

cerca <VideoName> stagione <SeasonNumber> episodio <EpisodeNumber>

trova <VideoName> stagione <SeasonNumber> episodio <EpisodeNumber>

busca el segundo episodio de la primera temporada de anabel*

<title> シーズン<SeasonNumber> エピソード<EpisodeNumber> を探して

procurar por <VideoName>episódio <EpisodeNumber>procurar por

<VideoName>temporada <SeasonNumber>procurar por <VideoNumber>temporada

breaking bad season दो episode five के लिये ढूँढ़ो/ढूँढ़ना/खोजो/खोजना/search करना

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

1.0

Search by franchise <title>

Search for star trek

such nach? <VideoName> such/zeig/find film? <VideoName> auf <AppName>

zeig mir film? <VideoName> auf <DeviceBrand>

such trailer von <VideoName>

cherche star trek

recherche <VideoName>

cherche <VideoName>

cerca <VideoName>

trova <VideoName>

busca shrek

procurar<VideoName>

start trek के लिए ढूँढ़ो/ढूँढ़ना/खोजो/खोजना/search करना

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

1.0

Search by Character Name

Search for james bond

Not supported

cherche un film avec <charactername>

recherche un film avec <charactername>

cherche un film avec <charactername>

cerca un film con <CharacterName>

trova un film con <CharacterName>

busca películas de la pantera negra

<CharacterNameName>が主人公の<MediaType>を探して

not supported

<CharacterName> movie दिखाओ/खोजो <CharacterName> के/का/की/वाला movie <VideoName> दिखाओ/खोजो/ढूँढो

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

1.0

Search by director name

Search for quentin tarantino

such nach <MediaType> mit <ActorName>

such <ActorName> <MediaType>

zeig <MediaType> mit <ActorName>

cherche un film de quentin tarantino

recherche un film de <DirectorName>

cherche un film de <DirectorName>

cerca <DirectorName>

busca las películas de alejandro lozano

not supported

quentin tarantino के लिए ढूँढ़ो/ढूँढ़ना/खोजो/खोजना/search करना

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

1.0

Search by production company

Search for disney

suche nach <ProductionCompany> filmenzeige mir <ProductionCompany> filme

cherche des films de disney

recherche des films de disney

cherche des films de disney

cerca disney

busca películas de disney

<ProductionCompany>を検索

Procurar/procura/procure por <ProductionCompany>

disney के लिए ढूँढ़ो/ढूँढ़ना/खोजो/खोजना/search करना

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

1.0

Search by genre name

Search for comedy

zeig <GenreNameName> filme auf <AppName>

such nach <GenreName> <MediaType>

cherche une comédie

recherche un/une <GenreName>

cherche un/une <GenreName>

cerca <GenreName>

trova <GenreName>

busca comedias románticas

<GenreNameName>の<MediaType>を見つけて

procurar por <GenreName>

<GenreName> movies दिखाओ/ढूँढो

<ActorName> के/का/की/वाला <GenreName> movies दिखाओ/खोजो/ढूँढो

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).

1.0

Search by sports team

Search seahawks

Not supported

Not supported

not supported

busca el partido del real madrid

<Sport>の<Event>を見つけて<SportTeam>の<Event>を見つけて

procurar por<SportTeam>

<Sport/League/Seam> games दिखाओ/खोजो/ढूँढो

<Sport> के <Event> को दिखाओ/खोजो <Sport> के <Event> को दिखाओ/खोजो

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

1.0

Search by sports type

Search for soccer

such <Sport> <Event>

find <Sport> <Event>

Not supported

Not supported

cerca <Sport>

trova <Sport>

enséña nos un vídeo de fútbol

<Sport>の<Event>を見つけて<SportTeam>の<Event>を見つけて

procurar por <Sport>

<Sport/League/Seam> games दिखाओ/खोजो/ढूँढो

<Sport> के <Event> को दिखाओ/खोजो

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

1.0

Search by sports league

Search for n. b. a. league

Not supported

cherche <league>

recherche <league>

cherche <league>

not supported

busca el partido de la

n. b. a.

<Sport>の<Event>を見つけて<SportTeam>の<Event>を見つけて

procurar por <League>

<Sport/League/Seam> games दिखाओ/खोजो/ढूँढो

<Sport> के <Event> को दिखाओ/खोजो

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

1.0

Search by sports event

Search for soccer game

such <Sport> <Event>

find <Sport> <Event>

Not supported

Not supported

cerca partite di <SportName>

trova partite di calcio

busca el partido de fútbol

<Sport>の<Event>を見つけて<SportTeam>の<Event>を見つけて

procurar por <SportName>

<Sport/League/Seam> games दिखाओ/खोजो/ढूँढो

<Sport> के <Event> को दिखाओ/खोजो

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

1.0

Launch <partner> app

Launch netflix app

starte <AppName>

spiel/öffne <AppName> app

starte <AppName> auf <DeviceBrand>

lance <AppName>

pars <AppName>

lancia <AppName>

apri <AppName>

lanza la app de netflix

lanza netflix

abrir <AppName>

netflix 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.

1.0

Launch special character title

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

starte <AppName>

spiel/öffne <AppName> app

starte AppName auf <DeviceBrand>

lance <AppName>

pars <AppName>

apri <special character AppName>

lanza i. b. e. x. treinta y cinco

abrir <special character AppName>

facebook 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.

1.0

Launch app

Launch app

starte <AppName>

spiel/öffne <AppName> app

starte AppName auf <DeviceBrand>

lance <AppName>

pars <AppName>

apri <AppName>

lanza la app de hulu

lanza youtube

abrir<AppName>

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.

1.0

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"
}

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 a list of video content entity types, see Entity Types for Video Content. Note that multimodal devices have the following additional entity types: 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
required

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." If the contentType is RECORDING, Alexa renders a prompt such as, "Here's the Academy Awards."

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. See Retrieve Image Size Data from the mediaIdentifier Object.

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.