GetDisplayableItemsMetadata Directives (Multimodal Devices)

Immediately after Alexa receives your Lambda's response to GetDisplayableItems, Alexa sends a GetDisplayableItemsMetadata request. The purpose of the GetDisplayableItemsMetadata directive is to retrieve information to properly show search results (not to play any content). The following diagram shows the expected Alexa directive and Lambda response:

GetDisplayableItemsMetadata Directive and Lambda GetDisplayableItemsMetadataResponse

Alexa Directive: GetDisplayableItemsMetadata

Alexa sends GetDisplayableItemsMetadata immediately before Alexa displays search results on the device. As such, Alexa might send this directive during search, browse, or landing page scenarios.

The request contains only a list of id values that Alexa needs metadata for. The id values are returned from you during the previous GetDisplayableItemsResponse that your Lambda sent.

Your Lambda's GetDisplayableItemsResponse response should contain metadata for Alexa’s voice response to the user, as well as metadata about icons, badging, selectionAction, etc.

GetDisplayableItemsMetadata Example

The following is an example GetDisplayableItemsMetadata directive:

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetDisplayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifiers": [
                {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                },
                {
                    "id": "channelId://provider1.channel.rp.1234-2345-63435-asdf"
                }
            ]
        }
    }
}

Payload Descriptions

The following table describes the payload fields in the GetDisplayableItemsMetadata directive.

Payload Descriptions
Field Description Data Type
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
mediaIdentifiers
required

Contains a list of `id` values for the media.

Array
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

Lambda Response: GetDisplayableItemsMetadataResponse

Your Lambda's response must contain the metadata information required to populate the templates on the device (provided by Amazon) and render the search results on the screen. The response contains only display-related information — no playback information is required in this case. 

GetDisplayableItemsMetadataResponse Example

The following an example of a GetDisplayableItemsMetadataResponse that your Lambda should send. This response provides a list of id values for the items to display on the device.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetDisplayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "The Big Bang Theory",
                    "contentType": "ON_DEMAND",
                    "releaseYear": "2014",
                    "selectionAction": "BROWSE",
                    "thumbnailImage": {
                        "contentDescription": "The Big Bang Theory Image",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "2h 49m"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Purchase Options",
                    "reviews": [
                        {
                            "totalReviewCount": 41951,
                            "type": "FIVE_STAR",
                            "ratingDisplayString": "4.06"
                        }
                    ],
                    "rating": {
                        "category": "PG-13"
                    }
                },
                {
                    "name": "The Big Bang Theory",
                    "contentType": "LIVE",
                    "releaseYear": "2011",
                    "selectionAction": "PLAY",
                    "thumbnailImage": {
                        "contentDescription": "The Big Bang Theory Image ",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "30 min"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "CC"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "Pilot"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "Play Now",
                    "rating": {
                        "category": "TV-PG"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "number": "1234",
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9",
                                "uri": "someUrl"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name",
                                "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true",
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

Example Payloads

The payload object for the GetDisplayableItemsMetadataResponse will contain different fields depending on the media. The following sample responses show the payload for different types of media.

Example Payload for an ON_DEMAND Movie

{
    "payload": {
        "searchResults": [
            {
                "name": "Interstellar",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "Interstellar Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h 49m"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "Purchase Options",
                "reviews": [
                    {
                        "totalReviewCount": 41951,
                        "type": "FIVE_STAR",
                        "ratingDisplayString": "4.06"
                    }
                ],
                "rating": {
                    "category": "PG-13"
                }
            }
        ]
    }
}

Example Payload for an ON_DEMAND TV Show

{
    "payload": {
        "searchResults": [
            {
                "name": "The Big Bang Theory",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "The Big Bang Theory Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h 49m"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "series": {
                    "seasonNumber": "1",
                    "episodeNumber": "1",
                    "seriesName": "The Big Bang Theory",
                    "episodeName": "Pilot"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "Purchase Options",
                "reviews": [
                    {
                        "totalReviewCount": 41951,
                        "type": "FIVE_STAR",
                        "ratingDisplayString": "4.06"
                    }
                ],
                "rating": {
                    "category": "PG-13"
                }
            }
        ]
    }
}

Example Payload for LIVE Content

{
    "payload": {
        "searchResults": [
            {
                "name": "Interstellar",
                "contentType": "LIVE",
                "releaseYear": "2011",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "Interstellar Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h 30 min"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "Play Now",
                "rating": {
                    "category": "PG-13"
                },
                "networkDetails": [
                    {
                        "channel": {
                            "number": "1234",
                            "callSign": "PBS",
                            "affiliateCallSign": "KCTS9",
                            "uri": "someUrl"
                        },
                        "channelMetadata": {
                            "name": "Alternate Channel Name",
                            "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                        },
                        "airingDetails": [
                              {
                                  "isLiveBroadcast": "true"
                                  "end": "2018-01-24T02:30:00Z",
                                  "start": "2018-01-24T00:00:00Z"
                              }
                          ]
                    }
                ]
            }
        ]
    }
}

Example Payload for Content That Can Be Browsed

{
    "payload": {
        "searchResults": [
            {
                "name": "The Big Bang Theory",
                "contentType": "RECORDING",
                "selectionAction": "BROWSE",
                "thumbnailImage": {
                    "contentDescription": "The Big Bang Theory Image",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "viewingDisplayString": "View episodes"
            }
        ]
    }
}

Payload Descriptions

The following table describes the payload fields for a GetDisplayableItemsMetadataResponse.

Payload Descriptions
Field Description Data Type
searchResults
required
The list of search results List
name
required

The name of the video. This is used to render a prompt to the user about the video that is going to be played. For example, "Here's Interstellar."

Example: Interstellar

String
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
releaseYear

Release year of video. This is used to display the release year when showing the item on the screen.

2018
String
selectionAction
required

Guidance on how to browse the entity when the user selects this item. For example, you may choose to group similar items together when sending the search results. Movies or TV shows can be grouped by Genre, or by Actor, etc. In such cases, you can drill down on the item by selecting the group and may view more results.

The following enum values are allowed:

  • BROWSE: This means that you can get browse node items on the grouped entity to view more results. In this case, Alexa ends up calling the GetBrowseNodeItems on the selected entity id.
  • PLAY: This means that the particular entity is not grouped and hence can be selected to play the item. In this case, Alexa ends up calling the GetPlayableItemsMetadata on the selected entity id.

Examples: BROWSE, PLAY

Enum
thumbnailImage
required

Image information that is used to display an image for the result item on the screen.

Example:

 {
  "contentDescription": "string",
  "sources": [
    {
      "url": "string",
      "size": "string",
      "widthPixels": integer,
      "heightPixels": integer
    },
    {
      "url": "string",
      "size": "string",
      "widthPixels": integer,
      "heightPixels": integer
    },
    { ... }
  ]
} 

Object
contentDescription
String
sources
Array
runtime
Details about the video runtime. Object
runTimeInMilliseconds
Duration of the video in milliseconds.

Example: 271871324

Long
displayString (runtime)
The formatted display string for the duration of the Video. This is used to show the duration on the screen.

Example: 2h 30m

String
closedCaption
Details about whether closed caption is available for the video and display information. Object
status (closedCaption)

Whether closed caption is available for the video. This is an enum with the following values:

  • AVAILABLE: This means that closed caption is available for the video.
  • NOT_AVAILABLE: This means that closed caption is not available for the video.

Examples: AVAILABLE,NOT_AVAILABLE

Enum
displayString (closedCaption)

The formatted display string to be shown on the screen for closed caption.

Example: CC

String
series

The metadata about the series if this item is part of a series. This information should be populated for TV shows only. If available, the information here is used to render prompts to the user for example, "Here's 'The Big Bang Theory' Season 1, episode 4.

Object
seasonNumber

The season number of the video.

Example: 1

String
episodeNumber

The episode number of the video.

Example: 3

String
seriesName
episodeName

The episode name.

Example: 4

String
absoluteViewingPositionMilliseconds
required

Progress offset of video in milliseconds based on the user's watch history. If the user has watched it previously, this represents some offset greater than 0. This is used to display a progress bar on the result item indicating how much has the user watched previously.

Example: 1248625

Long
parentalControl
required

Parental Control information based on the user and the video.

Object
pinControl
required

This field indicates whether parental control is required for the user for this video based on the setting. This is an enum with 2 values.

  • REQUIRED: This means that parental control applies to this item based on the user's setting. When this is set, there is a lock icon displayed on the item to suggest that parental control applies to this item and the user is required to enter a PIN to view the video.
  • NOT_REQUIRED: This means that parental control does not apply to this item based on the user's setting.

Examples: REQUIRED, NOT_REQUIRED

Enum
viewingDisplayString

The display string is shown on the screen with the result item and gives the user an indication of whether he/she can play immediately or has to go through buying/renting/subscribing, etc. Based on the entitlement status, the string can be different. The String needs to be localized based on the locale sent in the request

Example: Play Now, Subscribe

String
reviews
Information about the reviews for the video. List
totalReviewCount
Total count of reviews for the video.

Example: 13425

Long
type (review)
The type of review upon which information is based.

Example: FIVE_STAR

Enum
ratingDisplayString
>Rating of the video based for the type mentioned above and the reviews. This is used to display the rating under each item in the search results.

Example: 4.06

String
rating
Rating related information for the video. Object
category (rating)
Rating category of the video. E.g. PG-13. This is rating that applies for the region that this Video is resolved from. Also the rating value may differ based on the content for example, for movies, you may send us an MPAA rating like "PG-13" or for TV shows, you may send us a TV parental guidelines rating like "TV-PG."

Example: PG-13, TV-PG

String
networkDetails

Network details gives information about the network the program is airing from. For example, a new episode of "The Big Bang Theory" airing from CBS, or a live soccer game airing from ESPN. For on-demand content, this could be, for example, Prime Video displaying Game of thrones results from HBO. If the result item represents a live show (contentType = LIVE) on a channel, this object contains its metadata.

List
channel

Information about the channel the video is currently airing on.

Object
number (channel)
The channel number.

Example: 1234

callSign (channel)

Example: PBS

affiliateCallSign

Example: KCTS9

uri (channel)
channelMetadata

Metadata information about the channel.

Object
name (channelMetadata)
An alternate name for the channel.
image (channelMetadata)

Example: http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg

airingDetails

This object contains information on when content airs.

List
isLiveBroadcast

Whether this content is airing in real time. Set this true for live events like watching an NFL football game, or award shows like Oscars or Emmys, etc., that are happening in real time.

Set this false for content that was filmed prior to the original airing time. For example, a new episode of Big Bang theory that airs every Thursday. This must also be set to false for content that was once streamed in real time, like a football game in the past, but is no longer happening in real time.

Examples: true, false

boolean
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.
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.