Developer Console

GetPlayableItems Directives for Channel Navigation (VSK Echo Show)

When users say utterances to change the channel (e.g., "Watch PBS") the VideoContentProvider API sends a GetPlayableItems directive to your Lambda with information about the desired channel to play.

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

GetPlayableItems Directive and Lambda GetPlayableItemsResponse

Utterances for GetPlayableItems (Channel Navigation)

When users say the following channel change utterances, Alexa sends a GetPlayableItems directive to your Lambda. It's similar to the regular GetPlayableItems directive but with properties specific to channels.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

Go to fox

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

Go to channel thirteen

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

Go to channel k. c. p. q.

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

Watch fox

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

Watch channel thirteen

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

Va sur [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

va sur [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

cambia canal a t. p. d.

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

mets [ChannelName]

joue [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

mets la chaîne[ChannelNumber]

joue la chaîne[ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

Va sur [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

va sur [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

va sur [channel]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

mets [ChannelName]

joue [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

mets la chaîne[ChannelNumber]

joue la chaîne[ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

(schalt auf|geh zu) [ChannelName]

schalt kanal [ChannelName] ein

(geh|schalt|wechsel|änder) zum kanal [ChannelName]

(geh|schalt|wechsel|änder) zu [ChannelName] kanal

(wechsel|änder) den kanal zu [ChannelName]

(wechsel|änder) den kanal zu [ChannelName] auf [AppName]

schalt [ChannelName] auf [AppName] an

schalt kanal [ChannelName] auf [AppName] an

(geh|schalte|wechsel) zu [ChannelName] auf [AppName]

(stell|schalt) [ChannelName] ein auf [AppName]

(stell|schalt|wechsel) (um zu|auf) [ChannelName] auf [AppName]

schalt kanal [ChannelName] auf [AppName] an

mach [ChannelName] auf [AppName] an

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

schalt kanal [ChannelNumber] ein

(geh|schalt|wechsel|änder) zum kanal [ChannelNumber]

(geh|schalt|wechsel|änder) zu [ChannelNumber] kanal

(wechsel|änder) den kanal zu [ChannelNumber]

(wechsel|änder) den kanal zu [ChannelNumber] auf [AppName]

schalt [ChannelNumber] auf [AppName] an

schalt kanal [ChannelNumber] auf [AppName] an

(geh|schalte|wechsel) zu [ChannelNumber] auf [AppName]

(stell|schalt) [ChannelNumber] ein auf [AppName]

(stell|schalt|wechsel) (um zu|auf) [ChannelNumber] auf [AppName]

schalt kanal [ChannelNumber] auf [AppName] an

mach [ChannelNumber] auf [AppName] an

kanal [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

schalte/änder/geh zu/auf den fernsehsender [ChannelName]

geh zum (fernseh)kanal [ChannelName]

ändern den (fernseh)kanal zu/auf [ChannelName]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

[ChannelName] auf [AppName] ansehen

spiel den kanal [ChannelName] ab

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

Zeige Kanal/Sender [channel number]

Kanal/Sender [channel number] anschauen

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

fox पर/पे जाओ/जाइए/जाना/चलो/चलना

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

channel दस पर/पे जाओ/जाना/जाइए/चलो/चलना

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

channel sony पर/पे जाओ/जाना/जाइए/चलो/चलना

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

fox देखो/देखिए/देखना/देखें

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

channel बारह देखो/देखना/देखिए/देखें

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

vai su [ChannelName]

vai a [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

vai al [ChannelNumber]

vai su [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

vai su [Channel]

vai a [Channel]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

guarda [ChannelName]

fammi vedere [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

metti [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

[ChannelName]を検索

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

[ChannelName]を見せて

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

チャンネル[ChannelNumber]を見せて

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

vá/vai/ir para o canal [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

vá para o canal [CallSign]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

assistir/assiste/assista [ChannelName]Assistir/assiste/assistao [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

assitir canal [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

cambia a antena tres

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

cambia el canal a la dos

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

cambia canal a t. p. d.

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

ver la sexta

pon la sexta

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

pon canal dos

The view switches to the channel number, and content from the channel plays.

Note that here implementations for multimodal devices differ from Fire TV apps when it comes to channels. With Fire TV apps, there is a separate directive for channel navigation (ChangeChannel), whereas multimodal implementations use GetPlayableItems for both play utterances and channel navigation utterances, but with different properties.

GetPlayableItems Example (Channel Navigation)

The following is an example of a GetPlayableItems directive for a specific channel. The payload has fields unique to channel scenarios.

{
    "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": "Channel",
                    "value": "PBS",
                    "externalIds": {
                        "imdb": "tt4574334"
                    },
                    "entityMetadata": {
                        "channelCallSign": "KBTC",
                        "channelNumber": "123"
                    }
                }
            ],
            "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"
            }
        }
    }
}

Note that entities with "type": "Channel" contain information for a television channel.

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": {
      "imdb": "tt4574334"
  },
  "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
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.
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." If the contentType is RECORDING, Alexa renders a prompt such as, "Here's the Academy Awards."



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

The external IMDB identifier.



Example: tt4574334

String
entityMetadata
optional

A map of metadata associated with the channel.

Object
channelCallSign(channel)
optional

The call sign for the channel.



Example: KBTC

String
channelNumber(channel)
optional

The channel number.



Example: 1234

Integer

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 B01LTHZVKG
└─ imdb The IMDB identifier for the actor. String tt4034228
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
└─ imdb The external IMDB identifier String tt4034228
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
└─ imdb The IMDB identifier for the character. String character id
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
└─ imdb The external IMDB identifier String tt4034228
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
└─ imdb The IMDB identifier for the event. String tt4034228
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
└─ imdb The external IMDB identifier String tt4034228
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
└─ imdb The external IMDB identifier String tt4034228
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
└─ imdb The IMDB identifier for the league String tt4034228
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
└─ imdb The IMDB identifier for the sport String tt4034228
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
└─ imdb The IMDB identifier for this team. String tt4034228
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 B01LTHZVKG
└─ imdb The IMDB identifier String tt4034228
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
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": "NEW", "type": "Recency" } ..], ```

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 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": "4k", "type": "VideoResolution" } ..], ```

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.

Experience Types

Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote.

The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.

  • VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.

  • DEFAULT: The default displays of all search results list format, regardless of the device used for the search.

To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

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.

Response Example (Channel Navigation)

The following is an example GetPlayableItemsResponse related to a channel change scenario.

{
    "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": "channelId://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