Alexa.Audio.PlayQueue GetNextItem
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 is true:
- 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 item currently playing has the
NEXTcontrol enabled, and the user asks Alexa to skip to the next item, either by voice or in the Alexa app. - The user requests to turn shuffle on or off. In this case, Alexa discards the next track queued to play, and calls
GetNextItembecause changing the shuffle state likely changes which track to play next.
When the currently playing track has the NEXT control disabled and the user asks Alexa for the next song, Alexa tells the user that skipping forward is not allowed, and the GetNextItem request is not sent to the skill.
With the GetNextItem interface, your skill can enforce skip limits, such as no more than three skips forward or backward per hour, or a maximum of ten skips per day. When the GetNextItem request is triggered by the user ("isUserInitiated": true), the skill can optionally return an error response indicating that the user has reached the skip limit.
"isUserInitiated": false, the request should not apply to the user's skip limit because the request was not initiated by the user.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 GetNextItem request.
Header
For an overview of the header format, see message header.
| Field | Value | Type |
|---|---|---|
messageId |
A version 4 UUID | string |
namespace |
Alexa.Audio.PlayQueue |
string |
name |
GetNextItem |
string |
payloadVersion |
1.0 |
string |
Payload
The following table describes the fields in the payload of a GetNextItem 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 |
isUserInitiated |
A flag indicating whether the request is because the user explicitly asked to skip to the next song (true), or the current track will soon end and the next track is needed (false). |
Boolean |
Example GetNextItem requests
When Alexa needs to get the stream URI for a track to buffer it on the device for a smooth transition, Alexa sends a GetNextItem request as in the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio.PlayQueue",
"name": "GetNextItem",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"currentItemReference": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"content": {
"id": "1021012f-12bb-4938-9723-067a4338b6d0",
"metadataType": "TRACK"
}
},
"isUserInitiated": false
}
}
When the user says "Alexa, next" while a song is playing, Alexa sends a GetNextItem request as in the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio.PlayQueue",
"name": "GetNextItem",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"currentItemReference": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"content": {
"id": "1021012f-12bb-4938-9723-067a4338b6d0",
"metadataType": "TRACK"
}
},
"isUserInitiated": true
}
}
GetNextItem response
When the skill has a next item to return, it should send a GetNextItem.Response with the next item. When the currently playing item is the last item in the queue, the skill should send a GetNextItem.Response with "isQueueFinished": true to indicate that there are no more items. The skill can also reject a user's attempt to skip to the next item when enforcing skip limits.
Response structure
Following is the structure of a GetNextItem response.
Header
For an overview of the header format, see message header.
| Field | Value | Required? | Type |
|---|---|---|---|
messageId |
A version 4 UUID | yes | string |
namespace |
Alexa.Audio.PlayQueue |
yes | string |
name |
GetNextItem.Response |
yes | string |
payloadVersion |
1.0 |
yes | string |
Payload
The following table describes the fields in the payload of a GetNextItem response.
| Field | Description | Required? | Type |
|---|---|---|---|
isQueueFinished |
A flag that indicates whether the currently playing item is the last item in the queue. When this value is false, the item field must be present and contain a non-null value. When this value is true, the item field must be absent or set to null. |
yes | Boolean |
item |
The requested item in the play queue. See the Item object for more information. | yes | object |
Example GetNextItem responses
In the following example, the skill returns information about the next item that Alexa should play for the user.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio.PlayQueue",
"name": "GetNextItem.Response",
"payloadVersion": "1.0"
},
"payload": {
"isQueueFinished": false,
"item": {
"id": "533718fe-b22d-4f64-8b1c-49ffdb85f619",
"playbackInfo": {
"type": "DEFAULT"
},
"metadata": {
"type": "TRACK",
"name": {
"speech": {
"type": "PLAIN_TEXT",
"text": "in circles"
},
"display": "In Circles"
},
"art": {
"sources": [
{
"url": "https://images.example.com/images/cover/48x48-000000-80-0-0.jpg",
"size": "X_SMALL",
"widthPixels": 48,
"heightPixels": 48
},
{
"url": "https://images.example.com/images/cover/60x60-000000-80-0-0.jpg",
"size": "SMALL",
"widthPixels": 60,
"heightPixels": 60
},
{
"url": "https://images.example.com/images/cover/110x110-000000-80-0-0.jpg",
"size": "MEDIUM",
"widthPixels": 110,
"heightPixels": 110
},
{
"url": "https://images.example.com/images/cover/256x256-000000-80-0-0.jpg",
"size": "LARGE",
"widthPixels": 256,
"heightPixels": 256
},
{
"url": "https://images.example.com/images/cover/600x600-000000-80-0-0.jpg",
"size": "X_LARGE",
"widthPixels": 600,
"heightPixels": 600
}
]
}
},
"durationInMilliseconds": 276000,
"controls": [
{
"type": "COMMAND",
"name": "NEXT",
"enabled": true
},
{
"type": "COMMAND",
"name": "PREVIOUS",
"enabled": false
}
],
"rules": {
"feedbackEnabled": true
},
"stream": {
"id": "STREAMID_92_14629004",
"uri": "http://cdn.example.com/api/1/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
"offsetInMilliseconds": 0,
"validUntil": "2018-05-10T19:11:35Z"
},
"feedback": {
"type": "PREFERENCE",
"value": "POSITIVE"
}
}
}
}
When the skill determines that the user has reached their daily skip limit, it returns an error response indicating the error case as in the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio",
"name": "ErrorResponse",
"payloadVersion": "1.0"
},
"payload": {
"type": "SKIP_LIMIT_REACHED",
"message": "The user has reached their daily skip limit.",
"retryPeriod": "DAILY"
}
}
When the currently playing item is the last item in the queue, the skill returns a response indicating that there are no more tracks to return.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio.PlayQueue",
"name": "GetNextItem.Response",
"payloadVersion": "1.0"
},
"payload": {
"isQueueFinished": true
}
}
