Alexa Music, Radio, and Podcast Skill API Reference Overview

Alexa communicates with your skill code (AWS Lambda function) using a JSON message format. Alexa sends JSON-formatted requests that contain a header and a payload object to your skill. Then your skill returns a JSON-formatted response. For a high level workflow, see How a music skill works.

Your skill code reads the request headers to determine the message type. It uses information in the payload of the message to take the appropriate action with your music or radio service cloud, then sends a response indicating whether the action was successful. This page summarizes the interfaces and directives in the Alexa Music, Radio, and Podcast Skill API.

If you are a radio provider, you only need to implement Alexa.Media.Search GetPlayableContent, Alexa.Media.Playback Initiate, and Alexa.Media.PlayQueue GetItem. Currently, you can only create your skill using the Alexa Skills Kit Command Line Interface (ASK CLI). For the detailed steps, see Create a music or radio skill with the ASK CLI.

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.

Header
The header contains metadata about the type of message. The header contains a set of fields that are the same across message types (the fields are the same, but the values are not). For an overview of the header fields, see Message header.
Payload
The payload contains the data of the message. The fields in the payload vary by interface. For more information, see the documentation for each interface.

Message header

The following table describes the fields in a message header. 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)](https://en.wikipedia.org/wiki/Universally_unique_identifier).

 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

Interfaces and directives for a basic music experience

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

Alexa.Media.Search GetPlayableContent

See Alexa.Media.Search GetPlayableContent. The following table shows which content types use this directive:

Content type Required?
Music Required
Radio Required
Podcast Required

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. 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 request is made.

Alexa.Media.Playback Initiate

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

Content type Required?
Music Required
Radio Required
Podcast Required

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 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.PlayQueue GetItem

See Alexa.Media.PlayQueue GetItem. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Optional
Podcast 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 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

See Alexa.Audio.PlayQueue GetNextItem. The following table shows which content types use this directive:

Content type Required?
Music Required
Radio Required
Podcast Required

Alexa sends a GetNextItem request to the skill when a content queue exists and playback has started on the Alexa device, and one of the following conditions apply:

  • Content is playing on the Alexa 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

See Alexa.Audio.PlayQueue GetPreviousItem. The following table shows which content types use this directive:

Content type Required?
Music Required
Radio Required
Podcast Required

Alexa sends a GetPreviousItem request to the skill when a content queue exists and playback has started on the Alexa device, and one of the following conditions apply:

  • 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

See Alexa.Audio.PlayQueue JumpToItem. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Not applicable
Podcast Not applicable

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

Alexa.Media.PlayQueue SetShuffle

See Alexa.Media.PlayQueue SetShuffle. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Not applicable
Podcast Not applicable

When music is playing on an Alexa device and the user makes a request to enable or disable shuffle mode, Alexa sends a SetShuffle request to the skill. Implement this directive only if your music service supports shuffle mode.

Alexa.Media.PlayQueue SetLoop

See Alexa.Media.PlayQueue SetLoop. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Not applicable
Podcast Not applicable

When music is playing on an Alexa device and the user makes a request to enable or disable loop mode, Alexa sends a SetLoop request to the skill. Implement this directive only if your music service supports loop mode.

Interfaces and directives for a graphical control experience

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

Alexa.Media.PlayQueue GetView

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
Podcast Optional but recommended

When music is playing on an Alexa 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 the items that are coming up next.

Interfaces and directives for a personalized experience

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

Alexa.UserPreference ReceiveFeedback

See Alexa.UserPreference ReceiveFeedback. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Optional
Podcast Optional

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

Additional resources