Alexa Music 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 service cloud, then sends a response indicating whether the action was successful.

This page summarizes the interfaces in the Alexa Music Skill API.

API request and response structure

Requests and responses for all interfaces in the Alexa Music 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.

Field Description Required? Type
messageId A unique identifier for a single request or response. This is used for tracking purposes. The skill should log this information, but it should not use this information to support business logic. Any string of alphanumeric characters and dashes less than 128 characters is valid, but we recommend using a version 4 UUID, which is a UUID generated from random numbers. yes string
namespace The category of the message. The value depends on the interface. yes string
name The name of the message. The value depends on the interface. yes string
payloadVersion The version of the message payload. The value depends on the interface. yes string

Interfaces for a basic music experience

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

Alexa.Media.Search GetPlayableContent

See Alexa.Media.Search GetPlayableContent. This interface is 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 does not 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. This interface is 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. This interface is 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 interface only if the stream URIs returned by your music service cloud can expire.

Interfaces for a voice control experience

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

Alexa.Audio.PlayQueue GetNextItem

See Alexa.Audio.PlayQueue GetNextItem. This interface is 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. This interface is 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.Media.PlayQueue SetShuffle

See Alexa.Media.PlayQueue SetShuffle. This interface is optional.

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 interface only if your music service supports shuffle mode.

Alexa.Media.PlayQueue SetLoop

See Alexa.Media.PlayQueue SetLoop. This interface is optional.

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 interface only if your music service supports loop mode.

Interfaces 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 interfaces.

Alexa.Media.PlayQueue GetView

See Alexa.Media.PlayQueue GetView. This interface is 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.

Additional resources