Alexa.Media.Search Interface


Use the Alexa.Media.Search interface to enable your skill to search for content. In the following utterance, for example, a user asks to play audio content.

User: Alexa, play "Alive," from the album Ten, on Amazon Music.

Alexa sends your skill a GetPlayableContent request that contains information about the user and the requested content. If the content is available, the skill responds with a unique identifier.

Sometimes, as in the following example, a user asks to play content that's also displayable on devices with screens.

User: Alexa, show me songs by Adele.

When the content includes a visual component, Alexa sends your skill a GetDisplayableContent request. If the content is available, the skill returns a unique identifier.

In either type of request, GetPlayableContent or GetDisplayableContent, the response returns content items, if available, to satisfy the request. If the customer decides to play one of the returned items, the service sends an Initiate request to the skill. If the skill can't satisfy a given request, it returns an error code.

Utterances

When you use the Alexa.Media.Search interface, the voice interaction model is already built for you. The following examples represent typical user queries.

Alexa, play music on <skill name>.
Alexa, play top rock on <skill name>.
Alexa, I want to listen to Soundgarden on <skill name>.
Alexa, play "Alive," by Pearl Jam, on <skill name>.
Alexa, play the album Nevermind, by Nirvana, on <skill name>.
Alexa, I want to hear the Party Hits playlist on <skill name>.
Alexa, let me hear some jazz classics on <skill name>.
Alexa, play the Summertime station on <skill name>.
Alexa, wake me up to yacht rock on <skill name> at seven-thirty AM.
Alexa, set an alarm to <program series name> for <time> on <provider>.
Alexa, play the program <program series name>.
Alexa, play the Stuff You Should Know podcast.
Alexa, resume the podcast <program series name>.
Alexa, resume my podcast.
Alexa, play the latest <program in the current series>.
Alexa, play the oldest <program in the current series>.
Alexa, turn on <program series name> from <time>.
Alexa, play <program series name> about <topic>.
Alexa, play episode <program number> of <series name>.

When the user says one of these utterances, Alexa sends a corresponding GetPlayableContent directive to your skill.

Configure your skill to receive requests

You must configure your music skill to support the GetPlayableContent API before Alexa sends requests to it. The following table shows where to configure your skill.

Build method Configuration

Alexa Skills Kit (ASK) developer console

Interfaces page in the console

ASK command line interface (ASK CLI)

Skill manifest JSON

Directives

GetPlayableContent directive

Support the GetPlayableContent directive so that users can request content. The following table shows the content types that use this directive.

Content type Required

Music

Yes

Radio

Yes

Podcast

Yes

The following table shows the GetPlayableContent directive payload.

Field Description Type Required

requestContext

Context information about the request.

RequestContext object

Yes

filters

Filters to apply during content resolution.

Filter object

Yes

selectionCriteria

Attributes that your skill resolves to a content object to play for the user.

ResolvedSelectionCriteria object

Yes

For music skills, the following table shows the entity types in the selectionCriteria property and the music catalog associated with each type. These entity types apply only to selected play requests and search requests.

Entity Catalog type

TRACK

AMAZON.MusicRecording

ALBUM

AMAZON.MusicAlbum

ARTIST

AMAZON.MusicGroup

PLAYLIST

AMAZON.MusicPlaylist

GENRE

AMAZON.Genre

STATION

AMAZON.BroadcastChannel

For podcast skills, the following table shows that the entity types in the selectionCriteria property correspond to podcast catalogs associated with the skill.

Entity Catalog type

PROGRAM_SERIES

AMAZON.ProgramSeries

GetPlayableContent directive example (music)

The following example demonstrates the user request "Alexa, play 'Teach Your Children,' by Crosby, Stills, Nash & Young."

GetPlayableContent directive examples (podcast)

The following example demonstrates the user request "Alexa, play the podcast/program <program series name>."

The following example demonstrates the user request "Alexa, resume my podcast."

When a user says "Alexa, play the latest," the skill responds only if a program series is currently playing. This kind of request is made, for example, when the user wants to pause and then resume a program. Your skill must retrieve the current playing (last played) program series from the user's history and initiate playback of the latest—that is, the most recent—program the user has heard.

When a user says "Alexa, play the oldest season", the skill responds only if a program series is currently playing. This kind of request is made, for example, when the user wants to listen to a program series from the beginning. Your skill must retrieve the currently playing (last played) program series from the user's history and initiate playback of the program's earliest available season.

The following example demonstrates the user request "Alexa, play <provider name>." The skill receives this type of request with an empty selectionCriteria attributes list. Your skill must respond with the user's most recently played media. For skills that support multiple media types, the most recently played media need not be a podcast.

The following example demonstrates the user request "Alexa, play <program series name> from a week ago."

The following example demonstrates the user request "Alexa, play <program series name> about/with <topic name>."

The following example demonstrates support for subscription playback.

GetPlayableContent response

To handle a GetPlayableContent directive, respond with an Alexa.Response event.

If your skill receives a GetPlayableContent request and finds playable content to satisfy the request, it responds with a GetPlayableContent.Response. The following table shows payload details for GetPlayableContent.Response.

Field Description Type Required

content

Content that satisfies the request. For details, see the Content object.

Object

Yes

userContentProperties

(Podcasts only) User-specific information related to the returned content. For details, see the userContentProperties object.

Object

Yes

GetPlayableContent response example (music)

The following example response satisfies a user request like "Alexa, play the song Poker Face, by Lady Gaga."

GetPlayableContent response event examples (podcast)

The following example response satisfies the user request "Alexa, play <program series> on <skill name>."

The following example response satisfies the user request "Alexa, play <program series> on <skill name>". This response assumes that the user has listened to the program series before.

The following example shows the error response that the skill returns when it can't find playable content to satisfy the user's request.

Your skill must provide subscription playback support for commands like "Alexa, play my followed podcasts." If the user has episodes to play in their subscription queue, the response must include a PLAYLISTcontent object that includes a MediaMetadata object. Note that PLAYLIST metadata has the same structure as BaseMetadata. In the response payload, the <Subscription_Playlist_Name>, such as "My followed podcasts," is provider specific. The Alexa companion app or multimodal device displays this name in the Most recently played section.

GetPlayableContent directive error handling

Sometimes a skill can't handle a given GetPlayableContent directive. For example, the customer's subscription tier might not allow access to the requested content, or geographic restrictions might prohibit streaming to the user's location. In such cases, your skill must respond with a media-specific CONTENT_NOT_FOUND message. This message is associated with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For details, see Alexa Music, Radio, and Podcast Skill API Error Responses.

GetDisplayableContent

You can support the GetDisplayableContent directive so that your skill can return content items with displayable attributes, such as images and other metadata. In response to requests from Alexa or from users, these content items are returned in the Alexa app and on multimodal devices like Fire TV and Echo Show. The following table lists the content types that can use the GetDisplayableContent directive.

Content type Required

Music

No

Radio

No

Podcast

No

GetDisplayableContent request

When your skill receives a GetDisplayableContent request, the request contains information about the user and the resolved selection criteria. When a media provider receives a request for music or other audio content, the provider responds with corresponding content identifiers. To satisfy a request to find music similar to the current song, the provider responds with identifiers for appropriate content recommendations.

The tabbed panels in the following tables show GetDisplayableContent requests for various attributes.

Search, find, and browse

When users want to find a particular song or artist, or when they browse for new music that suits their preferences or mood, they use the Search, find, browse experience. Following are example utterances for this experience.

Alexa, show me songs by The Scorpions.
Alexa, show me hard rock songs.

Library content

A user can request displayable content by touch action from the Play tab of the Alexa mobile app. Content displayed in response to a touch-action request is called library content.

"Now Playing" recommendations

When an Alexa multimodal device, such as Echo Show or Fire TV, starts to play a new item, Alexa fetches contextual recommendations. The new item might be a song, a podcast episode, or a radio station. Alexa retrieves content identifiers for these contextual recommendations, and the items appear on the Now Playing screen. This experience is known as "Now Playing" recommendations.

End-of-queue recommendations

When all play queue items on an Alexa multimodal device finish playing, Alexa fetches contextual suggestions called end-of-queue recommendations. The end-of-queue recommendations experience is the same as the "Now playing" experience except that Alexa also shares the last item played in the queue. The following code example shows a typical request for the end-of-queue experience.

Non-contextual recommendations

On multimodal devices, recommendations from the user’s default music provider appear periodically on the Home Cards. These cards rotate on and off the screen when the device is not in use. Recommendations also appear in widgets. These experiences are known as non-contextual recommendations. Recommendations and widgets are enabled by default on multimodal devices, but users can opt out of them in Settings.

Editorial widgets

On multimodal devices, editorial widgets let content creators feature special content, such as "Top 10 Podcast Episodes" or "Best Songs of the '80s." Alexa initiates the widget experience with a GetDisplayableContent request.

The following table shows payload details for the GetDisplayableContent directive.

Field Description Type Required

header.messageId

Unique identifier used to track a single request.

String

Yes

header.payloadVersion

Message payload version. Value is 2.0.

String

Yes

header.namespace

Message category. Value is Alexa.Media.Search.

String

Yes

header.name

Message name. Value is GetDisplayableContent.

String

Yes

payload.requestContext

Context information about the request.

RequestContext object

Yes

payload.Filters

Filters to apply during content resolution.

Filters object

Yes

payload.endpoints

A list of target playback endpoints. For details, see the Endpoint object.

Array of Endpoints objects

No

payload.maxResultLimit

Maximum number of results returned

Integer

Yes

alexaResolvedSelectionCriteria

A list of ResolvedSelectionCriteria objects. Each ResolvedSelectionCriteria object is returned in a catalog search and resolved to content that is displayed on screen.

Array of ResolvedSelectionCriteria objects

Yes

playQueuePreviewCriteria

An object that specifies the number of items to be sent to the play queue for the preview during the playback initiation. This object accepts previewItemLimit as the property name and a positive integer as the value. When this object is present in the request, Alexa requires that you return the preview metadata in the playQueuePreview response object. For details, see PlayQueuePreview.

Object

No

GetDisplayableContent response

If your skill receives a GetDisplayableContent request and finds displayable content to satisfy the request, it responds with GetDisplayableContent.Response. The following table shows payload details for GetDisplayableContent.Response.

Field Description Type Required

header.messageId

Unique identifier used to track a single request.

String

Yes

header.payloadVersion

Version of the message payload. Value is 2.0.

String

Yes

header.namespace

Message category. Value is Alexa.Media.Search.

String

Yes

header.name

Message name. Value is GetDisplayableContent.Response.

String

Yes

payload.contentGroups

List of objects, each of which describes a content item and associated metadata.

Array of ContentGroup objects

Yes

ContentGroup object

The following table shows the ContentGroup object. It contains a list of content to be rendered on a visual interface, and the metadata associated with that content.

Field Description Type Required

metadata

Metadata associated with the ContentGroup. For details, see the ContentGroupMetadata table that follows.

Object

Yes

contentList

List of content in the contentGroups. For details, see Content. If the GetDisplayableContent request contains the optional playQueuePreviewCriteria, the GetDisplayableContent response must return the playQueuePreview response object. For details, see PlayQueuePreview.

Array of objects

Yes

ContentGroupMetadata object

The following table shows the ContentGroupMetadata object. It contains a list of metadata for the items in the ContentGroup.

Field Description Type Yes

name

Localized name that describes an item in ContentGroup. This name can be displayed or spoken.

Object

Yes

GetDisplayableContent response structure

The following code example shows the response structure for a voice or touch-action GetDisplayableContent request. The structure is the same for all GetDisplayableContent experiences.

GetDisplayableContent directive error handling

If your skill can't handle a given GetDisplayableContent directive, the skill must respond with a media-specific CONTENT_NOT_FOUND message. This message is associated with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For details, see Alexa Music, Radio, and Podcast Skill API Error Responses.


Was this page helpful?

Last updated: Feb 09, 2024