GetPlayableItems Directives (VSK Echo Show)

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
- Entity Types
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
Watch [title] Required for certification	Watch breaking bad	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	Watch sean connery	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.
Watch by genre name Required for certification	Watch comedy	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.
Watch by franchise [title] Required for certification	Watch star trek	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	Watch a movie	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.
Watch [title] with season number Optional	Watch breaking bad 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.
Watch [title] with episode number Optional	Watch breaking bad 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.
Watch [title] with season and episode number Optional	Watch breaking bad season two episode five	The content corresponding to the requested season and episode plays.
Watch by character name Optional	Watch james bond	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.
Watch by sports team Optional	Watch seahawks	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.
Watch by sports type Optional	Watch soccer	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.
Watch by sports league Optional	Watch n. b. a. 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.
Watch by sports event Optional	Watch soccer game	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	mets / joue / lance / pars [VideoName] sur [AppName]	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	regarde un film avec [actor] mets un film avec [actor] joue un film avec [actor] pars un film avec [actor]	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.
Watch by genre name Required for certification	regarder un [GenreName] regarder une [GenreName] mets un [GenreName] mets une [GenreName] joue un [GenreName] joue une [GenreName	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.
Watch by franchise [title] Required for certification	regarde [title] mets [title] joue [title] pars [title]	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	regarde un film mets un film joue un film pars un film	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.
Watch [title] with season number Optional	regarde la saison [x] de [title] mets la saison [x] de [title] joue la saison [x] de [title] pars la saison [x] de [title] regarde [title] saison [x] mets [title] saison [x] joue [title] saison [x] pars [title] saison [x] joue la saison [x] de [title]	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.
Watch [title] with episode number Optional	regarde l'épisode [x] de [title] mets l'épisode [x] de [title] joue l'épisode [x] de [title] pars l'épisode [x] de [title] joue [title] épisode [x] mets [title] épisode [x]	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.
Watch [title] with season and episode number Optional	Same as fr-FR	The content corresponding to the requested season and episode plays.
Watch by character name Optional	Not supported	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.
Watch by sports team Optional	Regarde le [team] Regarde le match de [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.
Watch by sports type Optional	Not supported	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.
Watch by sports league Optional	Mets [league] Joue [league] Regarde [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.
Watch by sports event Optional	Not supported	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	mets / joue / lance [VideoName] sur [AppName]	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	regarde un film avec [actor] mets un film avec [actor] joue un film avec [actor]	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.
Watch by genre name Required for certification	regarder un [GenreName] regarder une [GenreName] mets un [GenreName] mets une [GenreName] joue un [GenreName] joue une [GenreName	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.
Watch by franchise [title] Required for certification	Regarde [title] Mets [title] Joue [title]	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	regarde un film mets un film joue un film	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.
Watch [title] with season number Optional	Regarde la saison [x] de [title] Mets la saison [x] de [title] Regarde [title] saison [x] Mets [title] saison [x] Joue [title] saison [x] Joue la saison [x] de [title]	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.
Watch [title] with episode number Optional	Regarde l'épisode [x] de [title] Mets l'épisode [x] de [title] Joue l'épisode [x] de [title] Joue [title] épisode [x]	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.
Watch [title] with season and episode number Optional	Regarde l'épisode [x] de la saison [x] de [title] Joue l'épisode [x] de la saison [x] de [title] Mets l'épisode [x] de la saison [x] de [title]	The content corresponding to the requested season and episode plays.
Watch by character name Optional	Not supported	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.
Watch by sports team Optional	Regarde le [team] Regarde le match de [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.
Watch by sports type Optional	Not supported	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.
Watch by sports league Optional	Mets [league] Joue [league] Regarde [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.
Watch by sports event Optional	Not supported	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	ich möchte [VideoName] gucken spiel [VideoName] spiel watchlist ab von [VideoName]	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	spiel [VideoName] (mit [ActorName]) auf [AppName] streame einen film mit [ActorName] auf [AppName] streame einen [ActorName] film auf [AppName] streame eine serie mit [ActorName] auf [AppName] streame eine [ActorName] serie auf [AppName]	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.
Watch by genre name Required for certification	spiel eine [GenreName] [MediaType] auf [DeviceType] ab spiel eine [GenreName] [MediaType] auf [AppName] ab [GenreName] [MediaType] schauen spiel einen [GenreName] [MediaType]	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.
Watch by franchise [title] Required for certification	ich möchte [VideoName] gucken spiel [VideoName] spiel watchlist ab von [VideoName]?	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	spiel einen [MediaType] spiel [MediaType] aus der/meiner watchlist streame den [MediaType] [VideoName] auf [AppName]/[Device] spiel trailer von [VideoName] spiel die neueste folge von [VideoName]	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.
Watch [title] with season number Optional	spiel [VideoName] [Season] [Season_Numer] spiel [VideoName] [Season] [Season_Numer] auf [AppName]	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.
Watch [title] with episode number Optional	spiel die [Episode_Number] [Episode] von [VideoName] spiel [VideoName] [Episode_Number] spiel von [VideoName] [Episode] [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.
Watch [title] with season and episode number Optional	spiel [Season] [Season_Numer] [Episode] [Episode_Number] von [VideoName] spiel [VideoName] [Season] [Season_Numer] [Episode] [Episode_Number] spiel die [VideoName] [Season] [Season_Numer] [Episode] [Episode_Number] auf [AppName] ab	The content corresponding to the requested season and episode plays.
Watch by character name Optional	Not supported	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.
Watch by sports team Optional	spiel [SportsTeam] [Event] auf [AppName] [SportsTeam] [Event] anschauen/ansehen das [SportsTeam] [Event] auf [AppName] anschauen/ansehen spiel das [SportsTeam] [Event] auf meinem [Device]	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.
Watch by sports type Optional	spiel das [Sport] [Event] auf meinem [Device] das [Sport] [Event] ansehen	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.
Watch by sports league Optional	spiel [SportsTeam] [Event] auf [AppName] [SportsTeam] [Event] anschauen	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.
Watch by sports event Optional	spiel das [Sport] [Event] auf meinem [Device] das [Sport] [Event] ansehen	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	[VideoName] चलाओ/बजाओ/लगाओ/play/देखो [AppName] पे/पर/में [VideoName] चलाओ/बजाओ/लगाओ/play	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	[ActorName] का/की/के movies को चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के movies चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के [GenreName] को चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के [GenreName] चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के [VideoName] को चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के [VideoName] चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के/वाला [GenreName] की [VideoName] को चलाओ/बजाओ/लगाओ/play/देखो [ActorName] का/की/के/वाला [GenreName] की [VideoName] चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch by genre name Required for certification	[GenreName] [VideoName] को चलाओ/बजाओ/लगाओ/play/देखो [GenreName] [VideoName] चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch by franchise [title] Required for certification	star trek देखो/देखना/देखिए	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	[VideoName] movies चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch [title] with season number Optional	[VideoName] का/की/के [SeasonNumber] को चलाओ/बजाओ/लगाओ/play/देखो [VideoName] का/की/के [SeasonNumber] चलाओ/बजाओ/लगाओ/play/देखो [VideoName] का/की/के [SeasonNumber] को चलाओ/बजाओ/लगाओ/play/देखो [VideoName] का/की/के [SeasonNumber] [SeasonNumber] चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch [title] with episode number Optional	[VideoName] का/की/के [EpisodeNumber] को चलाओ/बजाओ/लगाओ/play/देखो [VideoName] का/की/के [EpisodeNumber] चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch [title] with season and episode number Optional	[VideoName] season one episode one चलाओ/बजाओ/लगाओ/play करो [VideoName] season एक का episode एक चलाओ/बजाओ/लगाओ/play करो	The content corresponding to the requested season and episode plays.
Watch by character name Optional	[CharacterName] का/की/के/वाला movies चलाओ/बजाओ/लगाओ/play/देखो [CharacterName] का/की/के/वाला movies को चलाओ/बजाओ/लगाओ/play/देखो Watch [CharacterName] movie [VideoName]	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.
Watch by sports team Optional	[Sport/League/Seam] games चलाओ/बजाओ/लगाओ/play/देखो [Sport/League/Seam] के games को चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch by sports type Optional	[Sport/League/Seam] games चलाओ/बजाओ/लगाओ/play/देखो [Sport/League/Seam] के games को चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch by sports league Optional	[Sport/League/Seam] games चलाओ/बजाओ/लगाओ/play/देखो [Sport/League/Seam] के games को चलाओ/बजाओ/लगाओ/play/देखो	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.
Watch by sports event Optional	[Sport/League/Seam] games चलाओ/बजाओ/लगाओ/play/देखो [Sport/League/Seam] के games को चलाओ/बजाओ/लगाओ/play/देखो	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	metti / trasmetti / riproduci / fammi guardare / fammi vedere + [VideoName] (+ da/su [DeviceName])	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	guarda un film con [ActorName] metti un film con [ActorName]	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.
Watch by genre name Required for certification	guarda una [GenreName] fammi vedere una commedia mostra mi una commedia metti una commedia	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.
Watch by franchise [title] Required for certification	guarda star trek fammi vedere star trek mostra star trek	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	guarda un film metti un fim trasmetti un film riproduci un film	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.
Watch [title] with season number Optional	guarda [VideoName] stagione due metti [VideoName] stagione due riproduci [VideoName] stagione due	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.
Watch [title] with episode number Optional	guarda [VideoName] episodio cinque metti [VideoName] episodio cinque riproduci [VideoName] episodio cinque	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.
Watch [title] with season and episode number Optional	guarda [VideoName] stagione due episodio cinque metti [VideoName] stagione due episodio cinque riproduci [VideoName] stagione due episodio cinque	The content corresponding to the requested season and episode plays.
Watch by character name Optional	guarda [CharacterName] fammi vedere un film con james bond mostrami un film di james bond	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.
Watch by sports team Optional	riproduci la partita del [SportsTeam]	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.
Watch by sports type Optional	not supported	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.
Watch by sports league Optional	trasmetti la partita della [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.
Watch by sports event Optional	not supported	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	[VideoName]を再生して [VideoName]を[AppName]で再生して [AppName]で[VideoName][MediaType]を再生して	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	[ActorNameName]が出ている[MediaType]を再生	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.
Watch by genre name Required for certification	[AppName]で[GenreNameName][MediaType]を再生[AppName]で[GenreNameName]を再生	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.
Watch by franchise [title] Required for certification		Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	[VideoName]を再生して [VideoName]を＜AppName]で再生して [AppName]で[VideoName][MediaType]を再生して [MediaType]を再生して [ActorNameName]が出ている[MediaType]を再生 [Anaphor][MediaType]を流して [AppName]で[GenreNameName][MediaType]を再生 [AppName]で[VideoName][MediaType]を再生して [ChannelName]の[MediaType]を再生	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.
Watch [title] with season number Optional	[VideoName]の[Season][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.
Watch [title] with episode number Optional	[Episode_Number][Episode]を再生	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.
Watch [title] with season and episode number Optional	[Episode_Number][Episode]を再生 [VideoName]の[Season][Season_Number]の	The content corresponding to the requested season and episode plays.
Watch by character name Optional		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.
Watch by sports team Optional	[SportsTeam]の[Event]を[AppName]で見せて	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.
Watch by sports type Optional	[SportsTeam]の[Event]を[AppName]で見せて	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.
Watch by sports league Optional	[SportsTeam]の[Event]を[AppName]で見せて	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.
Watch by sports event Optional	[SportsTeam]の[Event]を[AppName]で見せて	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	tocar/assistir/reproduzir [VideoName] no/na [AppName]	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	assistir [ator] colocar [ator] coloque filmes com [ator] encontre filmes com [ator] me mostre filmes com [ator]	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.
Watch by genre name Required for certification	assitir [GenreName] assistir programas de [GenreName] programas de [GenreName] colocar [GenreName] por favor reproduzir [GenreName] reproduzir programas de [GenreName] colocar um programa de [GenreName]	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.
Watch by franchise [title] Required for certification	assitir jornada nas estrelas colocar jornada nas estrelas reproduzir jornada nas estrelas você pode passsar jornada nas estrelas por favor reproduzir jornada nas estrelas	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	assistir um filme colocar um filme nós podemos assistir um filme ver um filme	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.
Watch [title] with season number Optional	assistir [title] temporada [x] colocar [title] temporada [x] reproduzir [title] temporada [x]	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.
Watch [title] with episode number Optional	assistir [title] episódio [x] colocar [title] episódio [x] reproduzir [title] episódio [x] reproduzir o [title] episódio [x]	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.
Watch [title] with season and episode number Optional	assistir [title] temporada [x] episódio [x] colocar [title] temporada [x] episódio [x] reproduzir [title] temporada [x] episódio [x]	The content corresponding to the requested season and episode plays.
Watch by character name Optional	Not Supported	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.
Watch by sports team Optional	assisitr [SportTeam] assitir o/a [SportTeam] colocar no/na [SportTeam] colocar o jogo do/da [SportTeam] me mostre o jogo do/da [SportTeam] mostre o jogo do/da [SportTeam]	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.
Watch by sports type Optional	assistir [Sport]	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.
Watch by sports league Optional	assistir [League] colocar [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.
Watch by sports event Optional	not supported	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.

Feature	Sample Utterances	Expected Response
Watch [title] Required for certification	pon interstellar reproduce interstellar ver interstellar	The requested media plays. If there are multiple matches for the content, the user is prompted to select the desired media.
Watch by actor Required for certification	pon salma hayek reproduce salma hayek	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.
Watch by genre name Required for certification	pon comedia en netflix (Not supported without AppName)	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.
Watch by franchise [title] Required for certification	pon star wars reproduce star wars	Either the top recommended result for the requested franchise plays, or the user is presented with a list of matching franchises.
Watch by media type Optional	pon la película^* reproduce la película^* Note: Not supported in es-ES or es-US	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.
Watch [title] with season number Optional	empieza la segunda temporada de los rompecorazones comienza la segunda temporada de los rompecorazones reproduce la segunda temporada de los rompecorazones	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.
Watch [title] with episode number Optional	pon el capítulo final de los serrano	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.
Watch [title] with season and episode number Optional	pon el segundo episodio de la primera temporada de anabel reproduce el cuarto episodio de la temporada tres de águila roja	The content corresponding to the requested season and episode plays.
Watch by character name Optional	reproduce algo con james bond	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.
Watch by sports team Optional	ver el partido del real madrid	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.
Watch by sports type Optional	reproduce el partido de fútbol en mi televisor ver el partido de fútbol en mi tele ver el partido de fútbol	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.
Watch by sports league Optional	pon el partido de la a. c. b. en mi tele ver el partido de la a. c. b. en mi televisor	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.
Watch by sports event Optional	ver el partido de fútbol	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": {
                "start": "2016-09-01T00:00:00+00:00",
                "end": "2016-09-07T23:59: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` required	Entity types for video content. For a list of video content entity types, see Entity Types. 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` optional	A map of external identifiers for this entity; `key` is the provider, `value` is the `id`. Examples: `key` = `gti`, `value` = `SH000000012`	Object
`Gracenote` optional	The external Gracenote identifier. Example: `SP0000000666661`	String
`contentType` optional	`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` optional	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` optional	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` optional	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.

Entity Types

The entities object consists of a list of objects, each of which contains a type and a value along with other possible data such as external IDs. The following values are possible for the type value: Actor, App, Channel, Character, Director, Episode, Event, Franchise, Genre, League, MediaType, ProductionCompany, Season, Sport, SportsTeam, Video, Popularity, Recency, and VideoResolution. Details about the payloads for each entity type are provided in the sections below.

Actor

Actor represents an actor credited in video media content; for example, Casey Affleck might contain the following:

Actor Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `ASIN`	The external ASIN of this entity	String	`B01M3X9T06`
└─ `gracenote`	The Gracenote identifier for the actor.	String	`SP0000000666661`
`uri`	URI mapping to the actor/actress	URI	`entity://provider/actor/caseyaffleck`
`value`	The name of the actor	String	`Casey Affleck`

App

App represents the explicit app name specified by the user in utterance; for example, "Manchester by the Sea on Prime" might contain the following:

App Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `ENTITY_ID`	An application identifier from a list of apps.	String	`amzn1.alexa-ask-target.app.72095`
`value`	The name of the application	String	`Prime Video`

Channel

Channel represents the identifying data for a television channel; for example, "PBS" might contain the following:

Channel Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The external Gracenote identifier	String	`SP0000000666661`
`entityMetadata`	A map of meta data associated with the channel	Object	—
└─ `channelNumber`	The channel number	Integer	`1234`
└─ `channelCallSign`	The call sign for the channel	String	`KBTC`
`uri`	The URI of the channel	URI	`entity://provider/channel/1234`
`value`	The name of the channel	String	`PBS`

Character

A Character represented in video media content.

Character Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `ASIN`	The Amazon Standard Identification Number (ASIN) for this entity	String	`B00DT55P3K`
└─ `gracenote`	The Gracenote identifier for the character.	String	`ST0000000123456`
`uri`	URI mapping to the character	URI	`entity://provider/character/snowwhite`
`value`	The name of the character	String	`Snow White`

Director

Director represents the director name for the video media content; for example, "Kenneth Lonergan" might contain the following:

Director Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The external Gracenote identifier	String	`MV0000000666661`
`uri`	URI mapping to the director	URI	`entity://provider/director/kennethlonergan`
`value`	The name of the director	String	`Kenneth Lonergan`

Episode

Episode represents the episode number for serial content like TV Shows; for example, the eighth episode of "Transparent" would have episode number 8.

Episode Payload Fields	Description	Type	Example
`value`	The episode number	Integer	`8`

Event

An Event is a reference to a type of event; examples would include sports, music, or other types of events. For example, searching for "Football games" would search for a game event entity and a football sport entity.

Event Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The Gracenote identifier for the event.	String	`SP0000000666661`
`uri`	URI mapping to the event	URI	`entity://amazon/events/games`
`value`	The name of the event type	String	`Games`

Franchise

A Franchise is a video entity which can represent a number of video entities, like movies or TV shows. For example, take the fictional franchise "Intergalactic Wars" which represents a collection of movie trilogies, as well as animated and live action TV shows. This entity type was introduced to account for requests by customers such as "Find Intergalactic Wars movies", which would search for all "Intergalactic Wars" programs of the MOVIE value for MediaType, rather than attempting to match to a single title.

Franchise Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The external Gracenote identifier	String	`SP0000000666661`
`uri`	URI mapping to the franchise	URI mapping to the event	`entity://amazon/franchise/intergalacticwars`
`value`	The name of the genre	String	`Intergalactic Wars`

Genre

Genre represents the genre of video media content such as action, drama or comedy. For example, the Action genre might contain the following:

Genre Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The external Gracenote identifier	String	`SP0000000666661`
`uri`	URI mapping to the genre	URI	`entity://provider/genre/action`
`value`	The name of the genre	String	`Action`

League

League represents the categorical information for a sporting league; for example, NCAA is a league that might contain the following:

League Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The Gracenote identifier for the league	String	`SP0000000666661`
`uri`	URI mapping to the league	URI	`entity://amazon/league/ncaa`
`value`	The name of the league	String	`NCAA`

MediaType

MediaType represents the media type category of a particular piece of content; for example, the MediaType for "Manchester by the Sea" would be MOVIE.

MediaType Payload Fields	Description	Type	Example
`value`	The media type; possible values are `MOVIE`, `VIDEO`, `TV_SHOW`	Enum	`MOVIE`

ProductionCompany

ProductionCompany represents the production company name for the video media content; for example, Marvels, Disney.

ProductionCompany Payload Fields	Description	Type	Example
`value`	Production company name	String	`Marvel`

Season

Season represents the season number for serial content like TV Shows; for example, the season two of "Transparent" would have season number 2.

Season Payload Fields	Description	Type	Example
`value`	The season number	Integer	`2`

Sport

Sport represents the categorical information of a sport; for example, football is a sport that might contain the following:

Sport Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The Gracenote identifier for the sport	String	`SP0000000666661`
`uri`	URI mapping to the sports	URI	`entity://amazon/sport/football`
`value`	The name of the sport	String	`Football`

SportsTeam

SportsTeam represents the categorical information of a professional sports team; for example, "University of Washington Huskies" is a sports team that might contain the following:

SportsTeam Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
└─ `gracenote`	The Gracenote identifier for this team.	String	`SP0000000666661`
`uri`	URI mapping to the sports team	URI	`entity://amazon/sportsteam/huskies`
`value`	The name of the sports team	String	`University of Washington Huskies`

Video

Video represents the identifying data for the piece of video content; for example, "Manchester by the Sea" might contain the following:

Video Payload Fields	Description	Type	Example
`externalIds`	A map of external identifiers for this entity. Key is the provider, value is the id.	Object	—
`ASIN`	The external ASIN of this entity	String	`B01M3X9T06`
└─ `gracenote`	The Gracenote identifier	String	`MV0000000666661`
`userConfirmations`	Object containing information about user confirmations for the item	Object
└─ `entitlementVoiceActivation`	Flag to inform partner if voice enablement of viewing period or entitlement is successful. Possible values - `CONFIRMED` (optional).	Enum; Default policy - unrecognized values are ignored	`CONFIRMED`
`uri`	URI mapping to the video	URI	`entity://provider/movie/manchesterbythesea`
`value`	The name of the video	String	`Manchester by the Sea`

Popularity

Popularity indicates whether the user asks for popular content.

Popularity Payload Fields	Description	Type	Example
`value`	Indicates to provider that the user searches for popular content	String	`TRUE`

Note that this entity type does not have any `externalIds` included. A sample response (excerpted to the relevant values only) might look as follows: ```json "entities": [..{ "value": "TRUE", "type": "Popularity" } ..], ```

Recency

The resolved values for Recency indicate whether the user asks for new or old content.

Recency Payload Fields	Description	Type	Example
`value`	Indicates whether the user searches for new or old content; possible values are `NEW`, `OLD`	Enum	`NEW`

VideoResolution

VideoResolution represents the requested video resolution in one of the following standards:

SD (480p)
HD (720p-1080p)
4k (2160p)
8k (4320p)

VideoResolution Payload Fields	Description	Type	Example
`value`	Video resolution; possible values are `SD`, `HD`, `4k`, `8k`	Enum	`HD`

Note that multimodal devices have the following additional entity types: LISTTYPE, SORTTYPE.

LISTTYPE is populated when users wants to browse their Watchlist or Library. For example, utterances like "Show me my Watchlist" or "Show me my Video Library." LISTTYPE can have the following enum values:

WATCHLIST: For "Show me my Watchlist" — used to show videos the user has added to their watchlist.
LIBRARY: For "Show me my Video Library" — used to show videos that are in the users' library. Typically, these are the videos that have been purchased by the user.

SORTTYPE is used to give additional information about the request that should be used during the searches and how results need to be sorted. For example, for "Show me recommended movies," Alexa needs recommendations from the content provider. SORTTYPE can have the following enum value:

RECOMMENDED: This value is populated for utterances like "Show me recommended movies," or "Show me recommended action movies," etc.

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

Last updated: Nov 02, 2020