Your Alexa Consoles
Sign In
Sign In

Alexa.Media.PlayQueue SetLoop

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. This interface is optional. Implement this interface only if your music service supports loop mode.

Whenever a user asks for music to be looped, or to turn off loop, Alexa sends a SetLoop request. The skill must persist the current loop state (on or off) and associate it to the currently playing queue of music.

For example, when a user is listening to the last track of an album with loop mode off, a GetNextItem response should indicate that there are no more items in the queue ("isQueueFinished": true). However, when a user turns on loop mode (Alexa sends a SetLoop request with "enable": true), a GetNextItem response should return the first track of the album when the last track of the album is playing. Similarly, with loop mode on, a GetPreviousItem response should return the last track of the album when the first track is playing.

The Alexa Music Skill API does not provide a way for a user to ask for music to start playing with loop mode on. When music is playing, however, the user can turn on or off loop mode through voice commands such as "Alexa, loop" or "Alexa, turn off loop".

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 SetLoop 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 SetLoop string
payloadVersion 1.0 string

Payload

The following table describes the fields in the payload of a SetLoop 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 loop mode. Boolean

Example SetLoop requests

When a user asks Alexa to turn on loop mode, Alexa sends a SetLoop request like the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media.PlayQueue",
    "name": "SetLoop",
    "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 loop mode, Alexa sends a SetLoop request like the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media.PlayQueue",
    "name": "SetLoop",
    "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 loop 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 SetLoop 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": {}
}