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

Tip: To understand the way the Alexa GetPlayableItems and GetPlayableItemsMetadata directives interact with your Lambda code, see Step 3: Understand the Alexa Directives and Lambda Responses.

Utterances for GetPlayableItems
Handling GetPlayableItems Directives
GetPlayableItems Example
Payload Descriptions
Lambda Response
Example Response
Payload Descriptions

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 Spiele {title} Öffne {title} mets breaking bad mets breaking bad joue breaking bad fai partire breaking bad metti breaking bad Pon la pelicula (title) Pon breaking bad Pon la pelicula (title) Pon breaking bad {title}を再生して {title}を見せて assistir {title} ver {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 a movie Spiele Filme Spiele einen Film mets un film je veux voir un film mets un film joue un film fai partire un film metti un film pon una película (quiero) ver una película pon una película pon una peli {media type}を再生して {media type}を見せて assistir filmes ver filmes एक {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 mets un film de sean connery mets un film avec sean connery metti film con adriano celentano fai partire un film con sean connery 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 {actor}を再生して {actor}を見せて assistir um filme com {actor/actress} ver um filme com {actor/actress} {actor}की movie चलाओ {actor} की film लगा दो	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} mets la saison 2 de breaking bad mets la deuxième saison de breaking bad mets la deuxième saison de breaking bad joue la deuxième saison de breaking bad metti la seconda stagione di breaking bad fai partire la seconda stagione di breaking bad Pon la temporada 2 de breaking bad pon la segunda temporada de breaking bad pon la temporada 2 de breaking bad pon la segunda temporada de breaking bad {title} シーズン{season number}を再生して {title} シーズン{season number}を見せて assistir {title} temporada {cardinal number} ver {title} temporada {cardinal number} {title} season two चलाओ {title} season two चला दो	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 mets le cinquième épisode de breaking bad joue le cinquième épisode de breaking bad metti il quinto episodio di breaking bad fai partire il quinto episodio di breaking bad pon el episodio 5 de breaking bad pon el capítulo 5 de breaking bad pon el episodio 5 de breaking bad pon el capítulo 5 de breaking bad {title} エピソード{episode number}を再生して {title} エピソード{episode number}を見せて assistir {title} episódio {cardinal number} ver {title} number} episódio {cardinal number} watch {title} episode five play {title} episode five	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 mets l' épisode 5 de la saison 2 de breaking bad mets l' épisode 5 de la deuxième saison de breaking bad metti il quinto episodio della seconda stagione di breaking bad fai partire il quinto episodio della seconda stagione di breaking bad pon el episodio 5 de la temporada 2 de breaking bad pon 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 {title} シーズン{season number}エピソード{episode number}を再生して {title} シーズン{season number}エピソード{episode number}を見せて assistir {title} {ordinal number} temporada episódio {cardinal number} ver {title} {ordinal number} temporada episódio {cardinal number} play {title} season two episode five {title} season two episode five लगाओ	The content corresponding to the requested season and episode plays.
Play by franchise <title>	Watch star trek Spiele {franchise title} Spiele {franchise title} Filme mets star trek je veux voir star trek mets star trek joue star trek metti star trek fai partire star trek pon star trek (quiero) ver star trek pon star trek pon una película de star trek {franchise title}を再生して {franchise title}を見せて assistir {franchise title} ver {franchise title} {franchise title} चलाओ watch {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 mets james bond mets un film de james bond metti james bond metti un film di james bond pon james bond (quiero) ver james bond pon james bond pon una película de james bond {character}を再生して {character}を見せて assistir filmes com {character name} ver filmes com {character name} {character name} की picture चलाओ {character name} की movie चलाओ	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 einen (title) (film/serie) ansehen mets un film policier mets une émission sportive mets film d' comédie mets une comédie metti una commedia fam mi vedere una commedia pon una comedia (quiero) ver una comedia pon una comedia pon una película de comedia {genre}を再生して {genre}を見せて assistir uma/um {genre name} ver uma/um {genre name} watch {genre name} play {genre name}	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} mets les bleus je veux voir les bleus mets les canadiens mets le match des canadiens fam mi vedere la Juventus <Aberdeen, ac milan> pon el Madrid (quiero) ver el Madrid pon el América pon el partido del América {sports team}を再生して {sports team}を見せて assistir {sports team} ver {sports team} {sports team} चलाओ {sports team} की game चलाओ	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 mets du foot je veux voir du foot mets du hockey mets le hockey fam mi vedere una partita di calcio metti la/una partita pon el fútbol (quiero) ver el fútbol pon fútbol ponme fútbol {sports type}を再生して {sports type}を見せて assistir {sports type} ver {sports type} watch {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 Mets la n.b.a. Je veux voir la n.b.a. mets la l. n. h. je veux regarder la l. n. h. fam mi vedere la n.b.a. metti l'n.b.a. pon la n. b. a. (quiero) ver la n. b. a. pon la n. b. a. ponme la n. b. a. {sports league}を再生して {sports league}を見せて assistir {sports league} ver {sports league} watch {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} mets un match de foot/football je veux voir un match de foot/football mets une partie de hockey je veux regarder une partie de hockey metti una partita di calcio fam mi vedere una/la partita 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 {sports event}を再生して {sports event}を見せて assistir {sports event} ver {sports event} watch {sports event} play {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
Genres/Actors

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.

Tip: If Alexa finds the matching titles from your catalog, there should no need for you to do another search. You can use the information sent to you in the directive to select the correct video.

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. 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 category to be searched. Note that this is different from mediaType in the entities. MediaType specifies the type of media to search for, such as, Movies, or TV shows, and so on. So if the users are interested in browsing recorded movies, they would say something like Show me recorded movies. In this case, the mediaType will be set to `MOVIE`, while contentType will be set to `RECORDING`. Similarly, when the users want to Browse live tv content, they would say something like Show me whats on now, and, in this case ,the contentType will be set to `LIVE`." 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`. 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