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