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.
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.
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.
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.
To handle a GetPlayableContent directive, respond with an Alexa.Response event.
Important: Under moderate traffic conditions, your skill code (AWS Lambda function) must generate and return a response within 0.5 seconds. Moderate traffic means at least two transactions per second. A response time longer than 0.5 seconds might cause your skill to fail certification.
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.
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.
Copied to clipboard.
{"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."}}
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.
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.
Important: To onboard your skill to GetDisplayableContent, reach out to alexa-audio-getdisplayablecontent-spi-onboarding@amazon.com. In your message, include your skillId and a list of the experiences you'd like to support.
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.
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.
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.
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.
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.
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.
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.
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.
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.