Gracias por tu visita. Esta página solo está disponible en inglés.

GetPlayableItems Directives for Channel Navigation (VSK MM)

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

Go to Fox

Tune to ESPN

Schalte auf <channel>

Wechsel zu <channel>

Umschalten auf <channel>

Gehe zu <channel name>

<Sat Eins Emotions, Kabel Eins Doku, radio SAW>

Mets Fox

Va sur Fox

change à radio-canada

mets radio-canada

va à/sur radio-canada

joue radio-canada

passe à radio-canada

vai sulla Fox

cambia sulla Fox

metti la Fox

<alfa>

cambia a Fox

ve a Fox

abre Fox

cambia a t.v. Azteca

cámbiale a t.v. Azteca

cámbia le a t.v. Azteca

ve a t.v. Azteca

abre t.v. Azteca

{channel} 見せて

{channel} 開いて

{channel} に行って

{channel} をお願い

{channel} 選んで

{channel} を選択して

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

Go to channel number

Go to channel thirteen

Schalte auf <channel number>

Schalte auf Kanal/Sender <channel number>

Umschalten auf <channel number>

Mets la 5

Passe sur la 5

Va sur la 5

change au (poste) 10

mets le (poste) 10

va au/sur le (poste) 10

joue le (poste) 10

passe au (poste) 10

change au (canal) 10

mets le (canal) 10

va au/sur le (canal) 10

joue le (canal) 10

passe au (canal) 10

change à la chaîne 10

mets la chaîne 10

va à/sur la chaîne 10

joue la chaîne 10

passe à la chaîne 10

vai al canale 13

cambia sul canale 13

metti il canale 13

ve al canal 13

cambia al canal 13

ve al canal 13

cambia al canal 13

vete al canal 13

cámbiale al canal 13

cámbia le al canal 13

チャンネル {channel number} 開いて

チャンネル {channel number} に行って

チャンネル {channel number} をお願い

チャンネル {channel number} 選んで

チャンネル {channel number} 選択して

{channel number} チャンネル 開いて

{channel number} チャンネル に行って

{channel number} チャンネル をお願い

{channel number} チャンネル 選んで

{channel number} チャンネル を選択して

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

Go to channel callsign

Go to channel k. c. p. q.

Schalte auf <channel callsign>

Umschalten auf <channel callsign>

Mets la chaîne (channel code)

Passe sur la chaîne (channel code)

Va sur la chaîne (channel code)

change au ( canal ) (channel code)

mets le ( canal ) (channel code)

va au/sur le canal (channel code)

joue le canal (channel code)

change au poste (channel code)

mets le poste (channel code)

va/sur le au poste (channel code)

joue le poste (canal) channel code)

change à la chaîne (channel code)

mets la chaîne (channel code)

va à/sur la chaîne (channel code)

joue la chaîne (channel code)

vai al canale (code)

cambia sul canale (code)

metti il canale (code)

cambia al canal (channel code)

ve al canal (channel code)

cambia al canal (channel code)

ve al canal (channel code)

cámbiale al canal (channel code)

vete al canal (channel code)

cámbia e al canal (channel code)

vete al canal (channel code)

チャンネル {channel callsign} 見せて

チャンネル {channel callsign} 開いて

チャンネル {channel callsign} に行って

チャンネル {channel callsign} をお願い

チャンネル {channel callsign} を選んで

チャンネル {channel callsign} を選択して

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

Watch channel name

Watch fox

Zeige <channel name>

<channel name> anschauen

Spiel <channe name> ab

<Sat Eins Emotions, Kabel Eins Doku, radio SAW>

Mets Fox

Je veux voir/regarder Fox

Va sur Fox

Passe à Fox

mets radio-canada

va à/sur radio-canada

joue radio-canada

Je veux écouter/regarder/voir radio-canada

vai sulla Fox

cambia sulla Fox

metti la Fox

<alfa>

pon Fox

(quiero) ver Fox

pon t.v. Azteca

ponme t.v. Azteca

pon me t.v. Azteca

(quiero) ver t.v. Azteca

{channel name}を再生して

{channel name}を見せて

{channel name}を流して

{channel name}をかけて

{channel name}見たい

{channel name}をお願い

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

Watch channel number

Watch channel thirteen

Zeige Kanal/Sender <channel number>

Kanal/Sender <channel number> anschauen

Mets la 5

Je veux voir/regarder la 5

mets le (canal) 10

va au/sur le

joue le (canal) 10

Je veux écouter/regarder/voir le (canal) 10

vai al canale 13

cambia sul canale 13

metti il canale 13

pon el canal 13

(quiero) ver el canal 13

pon el canal 13

(quiero) ver el canal 13

ponme el canal 13

チャンネル {channel number} 見せて

{channel number} チャンネル 見せて

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 (ChannelChange), 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": {
                        "gracenote": "MV000000099001"
                    },
                    "entityMetadata": {
                        "channelCallSign": "KBTC",
                        "channelNumber": "123"
                    }
                }
            ],
            "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"
            }
        }
    }
}

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": {
      "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
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.
contentType

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
Gracenote

The external Gracenote identifier.

Example: ST0000000666661

String
entityMetadata

A map of metadata associated with the channel.

Object
channelCallSign

The call sign for the channel.

Example: KBTC

String
channelNumber

The channel number.

Example: 1234

Integer

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

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