Alexa.Media.PlayQueue SetShuffle
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. This interface is optional. Implement this interface only if your music service supports shuffle mode.
Whenever a user asks for music to be shuffled, or to turn off shuffle, Alexa sends a SetShuffle request. Example utterances include "Alexa, shuffle" and "Alexa, turn off shuffle". A SetShuffle request likely changes the skill's response to the next GetNextItem request. The skill must persist the current shuffle state (on or off) and associate it to the currently playing queue of music.
For example, when a user is listening to an album with shuffle mode off, a GetNextItem response should return the next track in the album. If shuffle mode is turned on by the user (Alexa sends a SetShuffle request with "enable": true), the skill should shuffle the album queue and respond to the next GetNextItem request with an out-of-order track. If shuffle mode is turned off by the user (Alexa sends a SetShuffle request with "enable": false), the skill should respond to the next GetNextItem request with the following track in the album.
The Initiate request determines the initial shuffle mode for the queue. The Initiate request contains a playbackModes.shuffle property that indicates whether to turn shuffle on or off for the queue. After a queue is created, SetShuffle can change the shuffle mode while music from the queue is playing.
After Alexa sends a SetShuffle request, Alexa discards the next item in the queue because changing the shuffle mode likely changes which track should be played next. Therefore, immediately after a SetShuffle request, Alexa sends a GetNextItem request to prepare the correct next track to play.
Configure a skill to receive requests
You must configure your music skill to support this API before Alexa will send requests to it. You can do this on the Interfaces page while building your skill in the Alexa Skills Kit developer console, or by adding the API to the interfaces object in your skill manifest JSON if you're using the ASK CLI to build your skill. For an example music skill manifest, see the example music skill manifest.
Request structure
Following is the structure of a SetShuffle request.
Header
For an overview of the header format, see message header.
| Field | Value | Type |
|---|---|---|
messageId |
A version 4 UUID | string |
namespace |
Alexa.Media.PlayQueue |
string |
name |
SetShuffle |
string |
payloadVersion |
1.0 |
string |
Payload
The following table describes the fields in the payload of a SetShuffle request.
| Field | Description | Type |
|---|---|---|
requestContext |
An object containing context information about the request. See the RequestContext object for more information. | object |
currentItemReference |
An object identifying the currently playing item. See the ItemReference object for more information. | object |
enable |
A flag that indicates whether to enable or disable shuffle mode. | Boolean |
Example SetShuffle requests
When a user asks Alexa to turn on shuffle mode, Alexa sends a SetShuffle request like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "SetShuffle",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
},
"enable": true
}
}
When a user asks Alexa to turn off shuffle mode, Alexa sends a SetShuffle request like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "SetShuffle",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
},
"enable": false
}
}
Response structure
When a skill can successfully set the queue's shuffle mode on or off as specified in the request, the skill should respond with a generic Alexa.Response acknowledgement.
Header
For an overview of the header format, see message header.
| Field | Value | Required? | Type |
|---|---|---|---|
messageId |
A version 4 UUID | yes | string |
namespace |
Alexa |
yes | string |
name |
Response |
yes | string |
payloadVersion |
3.0 |
yes | string |
Example SetShuffle response
The following example shows a generic Alexa.Response which indicates that the skill successfully handled the request.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3.0"
},
"payload": {}
}
