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

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.

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
required

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

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

Examples: RECORDING, LIVE, ON_DEMAND

Enum
locale
required

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

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

String
minResultLimit
required

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

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

Example: 8

Integer
maxResultLimit
required

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

Example: 25

Integer
timeWindow

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

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

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

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

Object containing start and end times.
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