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

GetPlayableItems Directives (VSK MM)

When users ask Alexa to play movies, TV shows, recordings, etc., using criteria such as VideoName, ActorName, or GenreName, the VideoContentProvider API sends GetPlayableItems directives to your Lambda.

The expected response from your Lambda is a GetPlayableItemsResponse, as shown in the following diagram.

GetPlayableItems Directive and Lambda GetPlayableItemsResponse

Utterances for GetPlayableItems

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

Feature Sample Utterances Expected Response
Play Title

Watch Breaking Bad

Play Interstellar

Spiele {title}

Öffne {title}

Gebe {title} wieder

Starte {title}

Zeige {title}

<Breaking Bad>

Mets Breaking Bad

Lance Breaking Bad

Mets/joue/fais jouer breaking bad

Fai partire breaking bad

Metti breaking bad

<House, The Office, Sneaky Pete>

Pon breaking bad

(quiero) ver breaking bad

Pon breaking bad

Ponme breaking bad

Pon me breaking bad

(quiero) ver breaking bad

{title}再生して

{title}見せて

{title}流して

{title}かけて

{title}見たい

{title}をお願い

The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.

Play by media type

Watch movies

Spiele Filme

Spiele einen Film

Mets un film

Mets les films

Je veux voir un film

Je veux voir des films

Je veux regarder un film

Je veux regarder des films

Mets-moi un film

Mets/joue/fais jouer un film

Je veux écouter/regarder/voir un film

fai partire un film

metti un film

fammi vedere un film

pon una película

pon películas

(quiero) ver una película

(quiero) ver películas

pon una película

pon una peli

pon películas

ponme una película

ponme una peli

ponme películas

pon me una película

pon me una peli

pon me películas

(quiero) ver una película

(quiero) ver una peli

(quiero) ver películas

{media type}を再生して

{media type}を見せて

{media type}を流して

{media type}をかけて

{media type}見たい

{media type}をお願い

Either media matching the non-title request plays (through an algorithm that selects a recommended video for the user), or a list of results is presented to the user.

Play by actor

Watch Sean Connery

Play a movie with Tom Hanks

spiele einen Film mit {actor} ab.

<Ann Blyth, Axel Deller, John Oliver>

Mets un film de Sean Connery

Je veux voir un film avec Sean Connery

Je veux voir un film de Sean Connery

Je veux regarder un film avec Sean Connery

Je veux regarder un film de Sean Connery

Mets-moi un film avec Sean Connery

Mets-moi un film de Sean Connery

Mets/joue/fais jouer un film de/avec Sean Connery

Je veux écouter/regarder/voir un film de/avec Sean Connery

fai partire un film con sean connery

metti un film con sean connery

fammi vedere un film con sean connery

<Gianni Franco, Sonia Scotti, Stefano Sani>

pon (una película) de Sean Connery

(quiero) ver (una película) de Sean Connery

pon (una película) de Sean Connery

ponme (una película) de Sean Connery

pon me (una película) de Sean Connery

(quiero) ver (una película) de Sean Connery

pon (una peli) de Sean Connery

ponme (una peli) de Sean Connery

pon me (una peli) de Sean Connery

(quiero) ver (una peli) de Sean Connery

{actor}再生して

{actor}見せて

{actor}流して

{actor}かけて

{actor}の{media type}を再生して

{actor}の{media type}見せて

{actor}の{media type}を流して

{actor}の{media type}をかけて

{actor}が出てる{media type}を再生して

{actor}が出てる{media type}見せて

{actor}が出てる{media type}を流して

{actor}が出てる{media type}をかけて

*{media type}:映画/ドラマ/やつ/もの/の

Either media with the actor plays (through an algorithm that selects the best match for the user), or a list of results is presented to the user.

Play <title> with season number

Watch breaking bad season two

Spiele {title} Staffel {X}

Spiele die {X}. Staffel von {title}

<Breaking Bad>

Mets la saison 2 de Breaking Bad

Mets la deuxième saison de Breaking Bad

Je veux regarder la saison 2 de Breaking Bad

Je veux voir la saison 2 de Breaking Bad

Je veux regarder la deuxième saison de Breaking Bad

Je veux voir la deuxième saison de Breaking Bad

Mets-moi la saison 2 de Breaking Bad

Mets-moi la deuxième saison de Breaking Bad

Mets/joue/fais jouer la deuxième saison/saison 2 de breaking bad

Je veux écouter/regarder/voir la deuxième saison/saison 2 de breaking bad

metti la seconda stagione di breaking bad

fai partire la seconda stagione di breaking bad

fammi vedere la seconda stagione di breaking bad

riproduci la seconda stagione di breaking bad

<House, The Office, Sneaky Pete>

Pon la temporada 2 de breaking bad

pon la segunda temporada de breaking bad

(quiero) ver la temporada 2 de breaking bad

(quiero) ver la segunda temporada de breaking bad

pon la temporada 2 de breaking bad

pon la segunda temporada de breaking bad

ponme la temporada 2 de breaking bad

ponme la segunda temporada de breaking bad

pon me la temporada 2 de breaking bad

pon me la segunda temporada de breaking bad

(quiero) ver la temporada 2 de breaking bad

(quiero) ver la segunda temporada de breaking bad

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

{title} シーズン{season number}を見せて

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

{title} シーズン{season number}をかけて

{title} シーズン{season number}見たい

{title} シーズン{season number}をお願い

The last-watched episode in the series plays, if the episode wasn't completed. If the last-watched episode was completed, the next unwatched episode plays.

Play <title> with episode number

Watch breaking bad episode five

Spiele {title} Folge 5 ab.

<Breaking Bad>

Mets l'épisode 5 de Breaking Bad

Mets le cinquième épisode de Breaking Bad

Je veux voir l'épisode 5 de Breaking Bad

Je veux voir le cinquième épisode de Breaking Bad

Je veux regarder l'épisode 5 de Breaking Bad

Je veux regarder le cinquième épisode de Breaking Bad

Mets-moi l'épisode 5 de Breaking Bad

Mets-moi le cinquième épisode de Breaking Bad

Mets/joue/fais jouer le/la cinquième épisode/épisode 5 de breaking bad

Je veux écouter/regarder/voir le/la cinquième épisode/épisode 5 de breaking bad

metti il quinto episodio di breaking bad

fai partire il quinto episodio di breaking bad

fammi vedere l'episodio cinque di breaking bad

<House, The Office, Sneaky Pete>

pon el episodio 5 de breaking bad

pon el capítulo 5 de breaking bad

(quiero) ver el episodio 5 de breaking bad

(quiero) ver el capítulo 5 de breaking bad

pon el episodio 5 de breaking bad

pon el capítulo 5 de breaking bad

ponme el episodio 5 de breaking bad

ponme el capítulo 5 de breaking bad

pon me el episodio 5 de breaking bad

pon me el capítulo 5 de breaking bad

(quiero) ver el episodio 5 de breaking bad

(quiero) ver el capítulo 5 de breaking bad

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

{title} エピソード{episode number}を見せて

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

{title} エピソード{episode number}をかけて

{title} エピソード{episode number}見たい

{title} エピソード{episode number}をお願い

The correct season is identified by the user's last-watched episode. The last-watched episode in the series plays, if the episode wasn't completed. If the last-watched episode was completed, the next unwatched episode plays.

Play <title> with season and episode number

Watch breaking bad season two episode five

Spiele {title} Staffel 2 Folge 5 ab.

<Breaking Bad>

Mets l'épisode 5 de la saison 2 de Breaking Bad

Mets l'épisode 5 de la deuxième saison de Breaking Bad

Je veux voir l'épisode 5 de la saison 2 de Breaking Bad

Je veux voir l'épisode 5 de la deuxième saison de Breaking Bad

Je veux regarder l'épisode 5 de la saison 2 de Breaking Bad

Je veux regarder l'épisode 5 de la deuxième saison de Breaking Bad

Mets-moi l'épisode 5 de la saison 2 de Breaking Bad

Mets-moi l'épisode 5 de la deuxième saison de Breaking Bad

Mets/joue/fais jouer le/la cinquième épisode/épisode 5 de la deuxième saison/saison 2 de breaking bad

Mets/joue/fais jouer (la) saison 2 épisode 5 de breaking bad
Je veux écouter/regarder/voir le/la cinquième épisode/épisode 5 de la deuxième saison/saison 2 de breaking bad
Je veux écouter/regarder/voir (la) saison 2 épisode 5 de breaking bad

metti il quinto episodio della seconda stagione di breaking bad

fai partire il quinto episodio della seconda stagione di breaking bad

metti l'episodio cinque della stagione due di breaking bad

fai partire l'episodio cinque della seconda stagione di breaking bad

<House, The Office, Sneaky Pete>

pon el episodio 5 de la temporada 2 de breaking bad

pon el episodio 5 de la segunda temporada de breaking bad

(quiero) ver el episodio 5 de la temporada 2 de breaking bad

(quiero) ver el episodio 5 de la segunda temporada de breaking bad

pon el episodio 5 de la temporada 2 de breaking bad

pon el episodio 5 de la segunda temporada de breaking bad

ponme el episodio 5 de la temporada 2 de breaking bad

ponme el episodio 5 de la segunda temporada de breaking bad

pon me el episodio 5 de la temporada 2 de breaking bad

pon me el episodio 5 de la segunda temporada de breaking bad

(quiero) ver el episodio 5 de la temporada 2 de breaking bad

(quiero) ver el episodio 5 de la segunda temporada de breaking bad

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

{title} シーズン{season number}エピソード{episode number}見せて

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

{title} シーズン{season number}エピソード{episode number}かけて

{title} シーズン{season number}エピソード{episode number}見たい

{title} シーズン{season number}エピソード{episode number}をお願い

The content corresponding to the requested season and episode plays.

Play by franchise <title>

Watch star trek

Spiele {franchise title}

Spiele {franchise title} Filme

<Star Wars, James Bond, Batman, Star Trek>

Mets Star Trek

Je veux voir Star Trek

Je veux regarder Star Trek

Mets-moi Star Trek

Mets/joue/fais jouer star trek

Je veux écouter/regarder/voir star trek

metti star trek

fai partire star trek

fammi vedere star trek

<Superman, cars, Scream>

pon star trek

(quiero) ver star trek

pon star trek

pon una película de star trek

pon una peli de star trek

ponme star trek

ponme una película de star trek

ponme una peli de star trek

pon me una película de star trek

pon me una peli de star trek

(quiero) ver star trek

(quiero) ver (una película de) star trek

{franchise title}再生して

{franchise title}見せて

{franchise title}流して

{franchise title}かけて

{franchise title}見たい

{franchise title}をお願い

Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.

Play by character name

Watch james bond

spiele einen Film mit {actor} ab.

<James Bond>

Mets James Bond

Je veux voir James Bond

Je veux regarder James Bond

Mets-moi James Bond

Mets un James Bond

Je veux voir un James Bond

Je veux regarder un James Bond

Mets-moi un James Bond

Mets/joue/fais jouer james bond

Je veux écouter/regarder/voir james bond

metti james bond

metti un film di james bond

fai partire un james bond

<Superman>

pon james bond

(quiero) ver james bond

pon james bond

pon una película de james bond

ponme james bond

ponme una película de james bond

pon me james bond

pon me una película de james bond

(quiero) ver james bond

(quiero) ver (una película de) james bond

{character}を再生して

{character}を見せて

{character}を流して

{character}をかけて

{character}の{media type}再生して

{character}の{media type}見せて

{character}の{media type}流して

{character}の{media type}かけて

{character}が出てる{media type}再生して

{character}が出てる{media type}見せて

{character}が出てる{media type}流して

{character}が出てる{media type}かけて

*{media type}:映画/ドラマ/やつ/もの/の

Either media matching the character name plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of media results.

Play by genre name

Watch comedy

spiele ein(e/n) {genre} ab.

<Familie,Architektur, Landestypisch>

Mets une comédie

Je veux voir une comédie

Je veux regarder une comédie

Mets-moi une comédie

Mets/joue/fais jouer une comédie

Je veux écouter/regarder/voir june comédie

metti una commedia

fammi vedere una commedia

fai partire una commedia

<Commedia>

pon una comedia

(quiero) ver una comedia

pon una comedia

pon una película de comedia

ponme una comedia

ponme una película de comedia

pon me una comedia

pon me una película de comedia

(quiero) ver una comedia

(quiero) ver una película de comedia

{genre}再生して

{genre}見せて

{genre}流して

{genre}かけて

{genre}見たい

{genre}をお願い

Either media from the requested genre plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of media results.

Play by sports team

Watch seahawks

Zeig mir {sports team}

Zeig mir das Spiel von {sports team}

Zeig mir Spiele von {sports team}

Zeig mir die Partie von {sports team}

Spiele von {sports team} anschauen

{sports team} anschauen

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

Mets les Bleus

Mets le match des Bleus

Je veux voir le match des Bleus

Je veux regarder le match des Bleus

Je veux voir les Bleus

Je veux regarder les Bleus

Mets-moi les Bleus

Mets-moi le match des Bleus

Mets/joue/fais jouer le/les Canadiens

Mets/joue/fais jouer le match/la partie/ la game du/des Canadiens

Je veux écouter/regarder/voir le/les Canadiens

Je veux écouter/regarder/voir le match/la partie/ la game du/des Canadiens

fammi vedere la Juventus

<Aberdeen, ac milan>

pon el Madrid

(quiero) ver el Madrid

pon el América

pon el partido del América

ponme el América

ponme el partido del América

pon me el América

pon me el partido del América

(quiero) ver el América

(quiero) ver el partido del América

{sports team}再生して

{sports team}見せて

{sports team}流して

{sports team}かけて

{sports team}見たい

{sports team}をお願い

Either media matching the sports team plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of media results.

Play by sports type

Watch soccer

Zeig mir {sports type}

{sports type} anschauen

Spiel {sports type} ab

Mets le foot

Je veux voir le foot

Je veux regarder le foot

Mets-moi le foot

Mets/joue/fais jouer du/le hockey

Je veux écouter/regarder/voir

du/le hockey

fammi vedere una partita di calcio

metti la/una partita

pon el fútbol

(quiero) ver el fútbol

pon fútbol

ponme fútbol

pon me fútbol

pon el fútbol

ponme el fútbol

pon me el fútbol

(quiero) ver fútbol

pon partidos de fútbol

(quiero) ver partidos de fútbol

{sports type}再生して

{sports type}見せて

{sports type}流して

{sports type}かけて

{sports type}見たい

{sports type}をお願い

Either media matching the sports type plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of results.

Play by sports league

Watch n. b. a. league

Zeig mir die {sports league}

{sports league} anschauen

Spiel {sports league} ab

Ruf {sports league} auf

Zeig {sports league} Spiele

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

Mets la n.b.a.

Je veux voir la n.b.a.

Je veux regarder la n.b.a

Mets-moi la n.b.a.

Mets un match de la n.b.a.

Je veux voir un match de la n.b.a.

Je veux regarder un match de la n.b.a

Mets-moi un match de la n.b.a.

Mets/joue/fais jouer (un match de/une partie de/ une game de) la LNH/NHL/Ligue nationale

Je veux écouter/regarder/voir (un match de/une partie de/ une game de) la LNH/NHL/Ligue nationale

fammi vedere la n.b.a.

metti l'n.b.a.

<America's Cup>

pon la n. b. a.

(quiero) ver la n. b. a.

pon la n. b. a.

ponme la n. b. a.

pon me la n. b. a.

(quiero) ver la n. b. a.

{sports league}を再生して

{sports league}を見せて

{sports league}を流して

{sports league}をかけて

{sports league}見たい

{sports league}をお願い

Either media matching the sports league plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of results.

Play by sports event

Watch soccer game

Zeig mir das {sports event}

Zeig mir ein {sports event}

Das {sports event} aufrufen

<wettkampf, spiel, match>

Mets un match de foot/football

Je veux voir un match de foot/football

Je veux regarder un match de foot/football

Mets-moi un match de foot/football

Mets/joue/fais jouer un match/une partie/ une game de hockey

Je veux écouter/regarder/voir un match/une partie/ une game de hockey

metti una partita di calcio

fammi vedere una/la partita

<gli europei>

pon el partido de fútbol

(quiero) ver el partido de fútbol

pon el partido de fútbol

ponme el partido de fútbol

(quiero) ver el partido de fútbol

{sports event}再生して

{sports event}見せて

{sports event}流して

{sports event}かけて

{sports event}見たい

{sports event}をお願い

Either media matching the sports event plays (through an algorithm that selects recommended media for the user), or the user is presented with a list of results.

Handling GetPlayableItems Directives

Alexa does the work of parsing the user's utterances and determining the intent, which Alexa then packages up into a GetPlayableItems directive. However, it might be unclear what the user wants to play, so Alexa sends you the requested content so you can do lookups for the item to play.

The response your Lambda sends should include basic identifying information about the playable content. Depending on your response, Alexa does the following:

  • If your Lambda returns just one item in the response, Alexa sends a GetPlayableItemsMetadata directive to initiate playback.
  • If your Lambda returns multiple items in the response, Alexa sends a GetDisplayableItemsMetadata directive to display search results.

The GetPlayableItems directive is identical to GetDisplayableItems, except for the header name. The GetPlayableItems directive is used when the user asks to play content on the device. Having separate directives for play and search allows for greater transparency around user intent. 

The following general guidance shows how to perform the search in different scenarios:

Video Names: For example, "Play Interstellar."

When a user includes the video name in the utterance ("Play Interstellar"), Alexa sends a GetPlayableItems directive with all the relevant video names found in your catalog, with catalog IDs included in the externalIds field. You should favor the content based on the IDs sent to you along with the videoNames, select the one that can be played, and then return that item.

Genres/Actors: For example, "Play a comedy movie" or "Play an action movie with Tom Cruise"

In the instance where a video name is not present and some other slot, such as genre and/or actor, is present, Alexa sends a GetPlayableItems directive. In these cases, you should perform a search using the entities sent in the directive.

For example, for an utterance like "Play an action movie," you receive {mediaType: MOVIE, genreName: COMEDY} in the GetPlayableItems directive. You can search based on this information and return an identifier for a comedy movie. 

Similarly for an utterance like "Play an action movie with Tom Cruise," you receive {mediaType: MOVIE, genreName: ACTION, actorName: Tom Cruise}in the GetPlayableItems directive. You can search and return an identifier for a movie that matches this criteria.

After you return the identifier in your response, Alexa sends a GetPlayableItemsMetadata directive to fetch additional metadata.

GetPlayableItems Example

The following is a sample GetPlayableItems directive. In this example, the media title (Manchester by the Sea) is explicitly identified by the user.

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetPlayableItems",
            "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"
            }
        }
    }
}

Payload Descriptions

The following table describes the payload for a GetPlayableItems directive.

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

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

Lambda Response

After receiving a GetPlayableItems directive, your Lambda must return a GetPlayableItemsResponse response that follows the structure here. The response structure in this case is similar to the response returned for the GetDisplayableItems directive.

Follow these guidelines in your response: 

  • Remember that the goal of the GetPlayableItems directive is to get a single item that can be played for the directive. 

  • If there is only one item to play, you can just return that one item, and Alexa will play the item. 

  • If it's not clear which item to play, you can choose to return multiple items in the response. Alexa will ask the user to choose which one to play. For example, if the user says, "Play Star Wars," there can be multiple movies in the Star Wars franchise returned in the response or multiple movies and TV shows pertaining to Star Wars. if you return multiple results, Alexa sends a GetDisplayableItemsMetadata directive to fetch the metadata and display search results. Note that the number of results returned in the first call should not exceed the resultLimit parameter specified in the directive.

  • If the only result found is not playable because the user is not entitled to play the title, or because a subscription is required, you can return that one item. Alexa fetches metadata and renders a prompt to either buy or rent or subscribe once Alexa finds that this item is not playable. After that, the user can trigger the purchase workflow to buy/rent the title and play it afterwards.

  • If multiple results are found that are not playable, you can choose to return all the results, and Alexa will either disambiguate with the user about which item to play, or render an informational prompt to buy, rent, or subscribe to the items.

  • If multiple results are found, with some playable and some not, then you should favor the playable one and return the playable result so that it can be played on the device.

Example Response

The following is an example response from your Lambda for GetPlayableItems:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "5f0a0546-caad-416f-a617-80cf083a05cd",
            "name": "GetPlayableItemsResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "nextToken": "fvkjbr20dvjbkwOpqStr",
            "mediaItems": [
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                },
                {
                    "mediaIdentifier": {
                        "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                    }
                }
            ]
        }
    }
}

Payload Descriptions

The following table describes the payload fields in a GetPlayableItemsResponse.

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