Step 6: Respond to Alexa Directives Delivered to Lambda (VSK Echo Show)
In this step, you need to code your Lambda function to respond to each of the six directives with the appropriate responses. There are six main directives: GetPlayableItems, GetPlayableItemsMetadata, GetDisplayableItems, GetDisplayableItemsMetadata, GetBrowseNodeItems, and GetNextPage. A comprehensive reference for this content is available in Requests and Responses Reference.
Your Lambda will need to interact with a backend service to retrieve the information. For example, when Alexa sends directives for your Lambda to process, the directives might involve retrieving information about specific media. You would need to write code that performs lookups for the media in your backend service and returns that information back to Alexa in the right JSON format.
Discovery
Through the discovery process, your skill is able to declare its capabilities to Alexa. These capabilities may be static for all users of your skill or change based on the user's subscription level with your service. Either way, your response to this directive establishes what a user can do with your skill.
Search
The GetDisplayableItems directive expects a collection of items to be returned in your Lambda's response. The response should contain identifiers for your content. A separate directive, GetDisplayableItemsMetadata, detailed in the following section, is made to retrieve metadata to play the content. The GetDisplayableItems and GetDisplayableItemsMetadata directives are separated into two requests to optimize latency.
GetDisplayableItems
When a user makes a search request such as "Alexa, show me <Title of Video Content>," Alexa sends a GetDisplayableItems directive to your Lambda, like this:
{
"directive": {
"header": {
...
"name": "GetDisplayableItems",
"namespace": "Alexa.VideoContentProvider",
...
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "accessToken",
}
},
"payload": {
"entities": [{
"type": "Video",
"value": "Title of Video Content",
"externalIds": {
"yourCatalogKey": "yourContentIdFromCatalog"
}
}],
"locale": "en-US",
"minResultLimit": 8,
"maxResultLimit": 25,
"timeWindow": {
"end": "2016-09-07T23:59:00+00:00",
"start": "2016-09-01T00:00:00+00:00"
}
}
}
}
Upon receiving this directive, your Lambda should provide a GetDisplayableItemsResponse response back to Alexa containing the requested media, like this:
{
"event": {
"header": {
...
"name": "GetDisplayableItemsResponse",
"namespace": "Alexa.VideoContentProvider",
...
},
"payload": {
"nextToken": "wwrfwef3",
"mediaItems": [
{
"mediaIdentifier": {
"id": "video://content.1234567"
}
},
{
"mediaIdentifier": {
"id": "video://content.4567890"
}
}
]
}
}
}
GetDisplayableItemsMetadata
When Alexa receives your GetDisplayableItemsResponse response, which contains the right content for the request, Alexa sends another directive called GetDisplayableItemsMetadata. The purpose of GetDisplayableItemsMetadata is to get information about the resolved content (such as images, titles, and other metadata) in order to populate the device's screen. The following example is a GetDisplayableItemsMetadata directive:
{
"directive": {
"header": {
...
"name": "GetDisplayableItemsMetadata",
"namespace": "Alexa.VideoContentProvider",
...
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "accessToken",
}
},
"payload": {
"mediaIdentifiers": [
{
"id": "video://content.1234567"
},
{
"id": "video://content.4567890"
}
]
}
}
}
When your Lambda receives a GetDisplayableItemsMetadata directive, you should provide a GetDisplayableItemsMetadataResponse response that provides metadata about the requested items. This metadata will often populate search results templates on the device.
{
"event": {
"header": {
...
"name": "GetDisplayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
...
},
"payload": {
"resultsTitle": "Search Results",
"searchResults": [
{
"title": "Video Name",
"contentType": "ON_DEMAND",
"thumbnailImage": {
"small": "https://.../image.jpg",
"medium": "https: //.../image.jpg",
"large": "https: //.../image.jpg"
},
/* ... rest of video 1 metadata ... */
},
{
/* ... video 2 metadata ... */
}
]
}
}
}
Landing Page
When a user opens your landing page (by saying "Alexa, open ACME video" or by saying "Video Home" and then selecting your video skill), Alexa sends two GetDisplayableItems directives:
-
The first
GetDisplayableItemsdirective is to retrieve categories for the landing page by setting theitemTypeproperty toCATEGORYand including asortTypeofRECOMMENDED. -
The second
GetDisplayableItemsdirective obtains the featured video for the landing page where the request sets theitemTypetoVIDEOinstead.
After receiving your response (GetDisplayableItemsResponse) for both directives, Alexa sends one GetDisplayableItemsMetadata call with a list combined of Category IDs and Video ID. The response includes metadata about the video as well as the categories. For the required fields for each itemType, see GetDisplayableItems and GetDisplayableItemsMetadata.
The following example is metadata for an itemType whose value is CATEGORY.
{
"name": "My Watchlist",
"contentType": "ON_DEMAND",
"itemType": "CATEGORY",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "My Watchlist Image",
"sources": [{
"url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}]
},
"mediaIdentifier": {
"id": "entity://provider/category/myWatchList"
}
}
Quick Play
Quick play scenarios (where users make requests such as "Alexa, play the movie [X]") use the GetPlayableItems and GetPlayableItemsMetadata directives, which are closely similar to GetDisplayableItems and GetDisplayableItemsMetadata. The only difference is that the metadata returned for playback varies slightly from that which is used for search. For more information, see GetPlayableItems and GetPlayableItemsMetadata).
Channel Navigation
Channel navigation utterances prompt Alexa to also send GetPlayableItems and GetPlayableItemsMetadata directives. The only difference is that the metadata returned for channel navigation varies slightly from that which is used for search/play. For more information, see GetPlayableItems.