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
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: 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.
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 However, if the request contains multiple entities of the same type, such as Let's say you have another request with 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.
{ "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:
Examples: |
String |
value required |
The value of the entity. For channels, the name of the channel. Examples: |
String |
externalIds |
A map of external identifiers for this entity; Examples: |
Object |
Gracenote |
The external Gracenote identifier. Example: |
String |
contentType required |
Examples: |
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 Examples: |
String |
minResultLimit required |
The minimum number of results to return in this call for which a For a Example: |
Integer |
maxResultLimit required |
A limit to the maximum number of results to return. See description of Example: |
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 — |
Object containing start and end times. |
start |
The start time of the time window. Examples: |
A string in ISO 8601 format. |
end |
The end time of the time window. Examples: |
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 theresultLimit
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
.
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 |
List |
mediaIdentifier required |
Identifier for the |
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 |
String |