Alexa Music, Radio, and Podcast Skill API Reference Overview

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.

Alexa communicates with your skill code (AWS Lambda function) using a JSON message format. Your skill code reads the request headers to determine the message type, and uses information in the message payload to take the appropriate action with your music or radio service cloud. Then it sends a response to indicate whether the action was successful.

This page summarizes the interfaces and directives in the Alexa Music, Radio, and Podcast Skill API. For a high-level workflow, see How a music skill works.

Note: Future releases of the Alexa Music, Radio, and Podcast Skill API might add new fields to the JSON request and response formats, while maintaining backward compatibility with the existing fields. Your skill code must be resilient to these changes. For example, your code for deserializing a JSON request must not break when it encounters a new, unknown field.

API request and response structure

Requests and responses for all interfaces in the Alexa Music, Radio, and Podcast Skill API contain a header and a payload. The header contains metadata about the message type. The set of fields in the header is the same across message types (that is, the fields are the same, but the values are not).

The following table describes the message header fields. All fields are present in all messages sent to your skill.

Field	Description	Type
`messageId`	A unique identifier for a single request or response. This is used for tracking purposes. Your skill should log this information, but it should not use this information to support business logic. When your skill generates message IDs to send in responses, you can use any string of alphanumeric characters and dashes up to 128 characters. As a best practice, consider using a version 4 universally unique identifier (UUID).	String
`namespace`	The category of the message. The value depends on the interface.	String
`name`	The name of the message. The value depends on the interface.	String
`payloadVersion`	The version of the message payload. The value depends on the interface.	String

The payload contains the message data. Payload fields vary by interface. For details, see the documentation for each interface.

Interfaces and directives for a basic music experience

To enable a basic music experience in your Alexa skill, implement the following interfaces and directives.

Note: If you're a radio provider, you must use the Alexa Skills Kit Command Line Interface (ASK CLI) to build your skill (for details, see Create a new skill by using the ASK CLI). You need to implement only three directives.
• Alexa.Media.Search GetPlayableContent
• Alexa.Media.Playback Initiate
• Alexa.Media.PlayQueue GetItem

Alexa.Media.Search GetPlayableContent

For details, see Alexa.Media.Search GetPlayableContent. The following table shows which content types use this directive.

Content type	Required
Music	Yes
Radio	Yes
Podcasts	Yes

When a user requests content from your skill, Alexa sends a GetPlayableContent request to the 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 responds with a content identifier that represents the requested song. The response doesn't initiate audio playback on the device. It indicates only whether the skill has audio content that satisfies the request. If the Alexa service determines that the audio content should be played, a subsequent request is made.

Alexa.Media.Playback Initiate

For details, see Alexa.Media.Playback Initiate. The following table shows which content types use this directive.

Content type	Required
Music	Yes
Radio	Yes
Podcasts	Yes

When Alexa receives a content identifier from the skill's GetPlayableContent response and is ready to start immediate playback of that content on an Alexa-enabled device, Alexa sends an Initiate request. The request includes the content identifier, and the skill responds with the stream URI for immediate playback of the content.

Alexa.Media.Playback Reinitiate

See Alexa.Media.Playback Reinitiate. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Not applicable
Podcasts	Not applicable

When audio is playing on one device and the user asks to move the audio stream to a different device, Alexa invokes Reinitiate. This capability lets users pause the play queue on one Alexa-enabled device and resume playback at the same point on another device. The Reinitiate interface captures specific information about the origin device, current play queue, and offset. This information, the playbackSnapshot, marks the point at which playback resumes on the target device.

Alexa.Media.PlayQueue GetItem

For details, see Alexa.Media.PlayQueue GetItem. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Optional
Podcasts	Optional

If an item's stream URI has expired, Alexa sends a GetItem request to obtain a new (refreshed) URI to begin playback on an Alexa-enabled device. Implement this directive only if the stream URIs returned by your music service cloud can expire.

Interfaces and directives for a voice control experience

To enable a voice control experience for your Alexa skill, implement the following directives.

Alexa.Audio.PlayQueue GetNextItem

For details, see Alexa.Audio.PlayQueue GetNextItem. The following table shows which content types use this directive.

Content type	Required
Music	Yes
Radio	Yes
Podcasts	Yes

Alexa sends a GetNextItem request to the skill when a content queue exists, playback has started on the Alexa-enabled device, and one of the following conditions applies.

Content is playing on the Alexa-enabled device, and Alexa needs to retrieve the next item to buffer on the device to ensure a smooth transition to the next item.
The user asks Alexa to skip to the next item.
The user chooses to skip to the next item (for example, in the Alexa app).

Alexa.Audio.PlayQueue GetPreviousItem

For details, see Alexa.Audio.PlayQueue GetPreviousItem. The following table shows which content types use this directive.

Content type	Required
Music	Yes
Radio	Yes
Podcasts	Yes

Alexa sends a GetPreviousItem request to the skill when a content queue exists, playback has started on the Alexa-enabled device, and one of the following conditions applies.

The user asks Alexa to skip back to the previous item.
The user chooses to skip back to the previous item (for example, in the Alexa app).

Alexa.Audio.PlayQueue JumpToItem

For details, see Alexa.Audio.PlayQueue JumpToItem. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Not applicable
Podcasts	Not applicable

Alexa sends a JumpToItem request to the skill when a content queue exists, playback has started on the Alexa-enabled device, and the user chooses the item in a play queue displayed in the Alexa app.

Alexa.Media.PlayQueue SetShuffle

For details, see Alexa.Media.PlayQueue SetShuffle. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Not applicable
Podcasts	Not applicable

When music is playing on an Alexa-enabled device and the user asks for shuffle mode to be enabled or disabled, Alexa sends a SetShuffle request to the skill. Implement this directive only if your music service supports shuffle mode.

Alexa.Media.PlayQueue SetLoop

For details, see Alexa.Media.PlayQueue SetLoop. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Not applicable
Podcasts	Not applicable

When music is playing on an Alexa-enabled device and the user asks for loop mode to be enabled or disabled, Alexa sends a SetLoop request to the skill. Implement this directive only if your music service supports loop mode.

Alexa.Media.PlayQueue SetRepeat

For details, see Alexa.Media.PlayQueue SetRepeat. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Not applicable
Podcasts	Optional

When music is playing on an Alexa-enabled device and the user asks for repeat mode to be enabled or disabled, Alexa sends a SetRepeat request to the skill. Implement this directive only if your music service supports repeat mode.

Interfaces and directives for a graphical control experience

To enable a graphical control experience for your Alexa skill, such as in the Alexa app and on Alexa-enabled devices with screens (such as the Echo Show), implement the following directives.

Alexa.Media.PlayQueue GetView

For details, see Alexa.Media.PlayQueue GetView. The following table shows which content types use this directive.

Content type	Required
Music	Optional but recommended
Radio	Optional but recommended
Podcasts	Optional but recommended

When music is playing on an Alexa-enabled device and the user navigates to the "play queue" view in the Alexa app, Alexa sends a GetView request to the skill. The skill responds with the item currently playing and (optionally) a list of upcoming items for display in the app. The skill chooses whether to respond with only the item currently playing or with a list of up to ten upcoming items. Alexa uses the response only for display in the Alexa app, so that users can see which items are coming up next.

Interfaces and directives for a personalized experience

To enable a personalized experience for your Alexa skill, such as in the Alexa app and on Alexa-enabled devices with screens (such as the Echo Show), implement the following directive.

Alexa.UserPreference ReceiveFeedback

For details, see Alexa.UserPreference ReceiveFeedback. The following table shows which content types use this directive.

Content type	Required
Music	Optional
Radio	Optional
Podcasts	Optional

When music is playing on an Alexa-enabled device and the user gives a negative or positive response, Alexa sends a ReceiveFeedback request to the skill.

Last updated: Feb 23, 2023