Alexa.Media.Search Interface

Implement the Alexa.Media.Search interface to enable your Alexa skill to search for content that a user has requested.

When a user requests content from your skill, Alexa sends a GetPlayableContent request to your skill. For example, if a user says "Alexa, play Alive from the album Ten on <skill name>", the skill receives a GetPlayableContent request that contains information about the user and the requested content. The skill can respond with a content identifier that represents the song Alive from the album Ten. If the skill can't satisfy the request – for example, the user's subscription tier doesn't support the content, or geographic streaming rights don't allow streaming to the user's location – the skill can respond with the appropriate error code.

The response doesn't initiate playback of audio on the device, it only indicates whether the skill has audio content that satisfies the request. If the Alexa service determines that the audio content should be played, a subsequent Initiate request is made.

Utterances

When you use the Alexa.Media.Search interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, play music on <skill name>.
Alexa, play top rock on <skill name>.
Alexa, play Soundgarden on <skill name>.
Alexa, play Alive by Pearl Jam on <skill name>.
Alexa, play the album Nevermind by Nirvana on <skill name>.
Alexa, play the playlist Party Hits on <skill name>.
Alexa, play rock music on <skill name>.
Alexa, play the Summertime station on <skill name>.
Alexa, wake me up to rock music 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, resume the podcast <program series name>.
Alexa, resume my podcast.
Alexa, play the latest (program of program series that's currently playing).
Alexa, play the oldest (program of program series that's currently playing).
Alexa, play <program series name> from <time>
Alexa, play <program series name> about <topic name>.
Alexa, play episode <program number> of <program series name>

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Configure your skill to receive requests

You must configure your music skill to support this API before Alexa will send requests to it. You can configure your skill in the following ways:

Directives

GetPlayableContent directive

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

Content type Required?
Music Required
Radio Required
Podcast Required

The following example shows a customer utterance:

Alexa, play the song Poker Face by Lady Gaga.

GetPlayableContent directive payload details

Field Description Type
requestContext Context information about the request. A RequestContext object.
filters Filters to apply during content resolution. A Filter object.
selectionCriteria Attributes that your skill resolves to a content object to play for the user. A ResolvedSelectionCriteria object.

For music skills, the entity types in the selectionCriteria property correspond to music catalogs associated with the skill as follows:

Entity Type Catalog Type
TRACK AMAZON.MusicRecording
ALBUM AMAZON.MusicAlbum
ARTIST AMAZON.MusicGroup
PLAYLIST AMAZON.MusicPlaylist
GENRE AMAZON.Genre
STATION AMAZON.BroadcastChannel

For podcast skills, the entity types in the selectionCriteria property correspond to podcast catalogs associated with the skill as follows:

Entity Type Catalog Type
PROGRAM_SERIES AMAZON.ProgramSeries

GetPlayableContent directive example (music)

GetPlayableContent directive examples (podcast)

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

The following example demonstrates a request from a user who says, "Alexa, resume my podcast."

The following example demonstrates a request from a user who says, "Alexa, play the latest." The skill receives this type of request only if it's currently playing a program series. This is a common case when the program series was played and resumed from the middle based on user's listening history. Your skill should identify the current playing (last played) program series from user history and respond with the latest program in the program series.

The following example demonstrates a request from a user who says, "Alexa, play the oldest season." The skill receives this type of request only if it's currently playing a program series. This is a common case when the user recognizes that they could be interested in the initial season of the program series. Your skill should identify the current playing (last played) program series from user history and respond with the earliest season within the program series.

The following example demonstrates a request from a user who says, "Alexa, play <provider name>." The skill receives this type of request with an empty selectionCriteria attribute list. Your skill must respond with most recently played media by the user. Note that the most recently played media need not be a podcast for skills that support multiple media types.

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

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

The following example demonstrates support for subscription playback.

GetPlayableContent response event

If you handle a GetPlayableContent directive successfully, respond with an Alexa.Response event.

If your skill can successfully find playable content to satisfy the request, it should respond with GetPlayableContent.Response.

GetPlayableContent response event payload details

Field Description Type Required
content The content to play, that satisfies the request. For details, see the Content object. Object Yes
userContentProperties (Podcast only) User-specific information related to the returned content. For details, see the UserContentProperties object. Object Yes

GetPlayableContent response event example (music)

The following example demonstrates a response that satisfies an example request from a user who says, "Alexa, play the song Poker Face by Lady Gaga."

GetPlayableContent response event examples (podcast)

The following example demonstrates a response that satisfies a request from a user who says, "Alexa, play <program series> on <skill name>."

The following example demonstrates a response when a user says, "Alexa, play <program series> on <skill name>", and the user has listened to the program series before.

In the following example, the skill can't find playable content to satisfy the user's request, so it returns an error response.

The following example demonstrates subscription playback support for "Alexa, play my followed podcasts.". If the customer has episodes to play from their subscription queue, the content object in the response should be a PLAYLIST type MediaMetadata object. Note that PLAYLIST metadata has the same structure as BaseMetadata. In the response payload, the <Subscription_Playlist_Name>, for example, "My followed podcasts," is provider-specific. The Alexa companion app displays this name in the Most recently played section.

GetPlayableContent directive error handling

If your skill can't handle a GetPlayableContent directive successfully, it should respond with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses.

If not, the skill should respond with a media-specific CONTENT_NOT_FOUND error response.

Last updated: Mar 22, 2023