Note: Sign in to the developer console to build or publish your skill.
Important: Anyone can build a music skill for public distribution in the United States. However, radio and podcast skills are currently in developer preview. To register your radio or podcast skill for the preview, contact your Alexa Music, Radio, or Podcast representative.
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:
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.
If you handle a GetPlayableContent directive successfully, respond with an Alexa.Response event.
Important: Your skill code (AWS Lambda function) should generate and return a response in 0.5 seconds or less under moderate traffic (at least two transactions per second). Longer response times might cause your skill to fail certification.
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.
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.
{"header":{"messageId":"2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b","namespace":"Alexa.Media","name":"ErrorResponse","payloadVersion":"1.0"},"payload":{"type":"CONTENT_NOT_FOUND","message":"Requested content could not be found."}}
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.
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_FOUNDerror response.