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
GetDisplayableItems
directive is to retrieve categories for the landing page by setting theitemType
property toCATEGORY
and including asortType
ofRECOMMENDED
. -
The second
GetDisplayableItems
directive obtains the featured video for the landing page where the request sets theitemType
toVIDEO
instead.
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
.