Developer Console

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

Utterances for GetPlayableItems

Alexa sends a GetPlayableItems directive to your Lambda when users say the following utterances.

Feature Sample Utterances Expected Response Complete

Handling GetPlayableItems Directives

Alexa does the work of parsing the user's utterances and determining the intent, which Alexa then packages up into a GetPlayableItems directive. However, it might be unclear what the user wants to play, so Alexa sends you the requested content so you can do lookups for the item to play.

The response your Lambda sends should include basic identifying information about the playable content. Depending on your response, Alexa does the following:

  • If your Lambda returns just one item in the response, Alexa sends a GetPlayableItemsMetadata directive to initiate playback.
  • If your Lambda returns multiple items in the response, Alexa sends a GetDisplayableItemsMetadata directive to display search results.

The GetPlayableItems directive is identical to GetDisplayableItems, except for the header name. The GetPlayableItems directive is used when the user asks to play content on the device. Having separate directives for play and search allows for greater transparency around user intent. 

The following general guidance shows how to perform the search in different scenarios:

Video Names: For example, "Play Interstellar."

When a user includes the video name in the utterance ("Play Interstellar"), Alexa sends a GetPlayableItems directive with all the relevant video names found in your catalog, with catalog IDs included in the externalIds field. You should favor the content based on the IDs sent to you along with the videoNames, select the one that can be played, and then return that item.

Genres/Actors: For example, "Play a comedy movie" or "Play an action movie with Tom Cruise"

In the instance where a video name is not present and some other slot, such as genre and/or actor, is present, Alexa sends a GetPlayableItems directive. In these cases, you should perform a search using the entities sent in the directive.

For example, for an utterance like "Play an action movie," you receive {mediaType: MOVIE, genreName: COMEDY} in the GetPlayableItems directive. You can search based on this information and return an identifier for a comedy movie. 

Similarly for an utterance like "Play an action movie with Tom Cruise," you receive {mediaType: MOVIE, genreName: ACTION, actorName: Tom Cruise}in the GetPlayableItems directive. You can search and return an identifier for a movie that matches this criteria.

After you return the identifier in your response, Alexa sends a GetPlayableItemsMetadata directive to fetch additional metadata.

GetPlayableItems Example

The following is a sample GetPlayableItems directive. In this example, the media title (Manchester by the Sea) is explicitly identified by the user.

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9f4803ec-4c94-4fdf-89c2-d502d5e52bb4",
            "name": "GetPlayableItems",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {

            }
        },
        "payload": {
            "entities": [
                {
                    "type": "Video",
                    "value": "Manchester by the Sea",
                    "externalIds": {
                        "gracenote": "MV000000099001"
                    }
                }
            ],
            "contentType": "RECORDING",
            "locale": "en-US",
            "minResultLimit": 8,
            "maxResultLimit": 25,
            "timeWindow": {
                "end": "2016-09-07T23:59:00+00:00",
                "start": "2016-09-01T00:00:00+00:00"
            }
        }
    }
}

Payload Descriptions

The following table describes the payload for a GetPlayableItems directive.

Payload Descriptions
Field Description Data Type












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





Last updated: