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": {}
}