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
- Interfaces and directives for a basic music experience
- Interfaces and directives for a voice control experience
- Interfaces and directives for a graphical control experience
- Interfaces and directives for a personalized experience
- Additional resources
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.