Alexa.Media.PlayQueue GetView
When music is playing on an Alexa device and the user navigates to the "play queue" view in the Alexa app, Alexa sends a GetView request to the skill. The skill responds with the item currently playing and (optionally) a list of up to ten upcoming items for display in the app. Alexa uses the response only for display in the Alexa app so that users can see the items that are coming up next.
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 GetView 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 |
GetView |
string |
payloadVersion |
1.0 |
string |
Payload
The following table describes the fields in the payload of a GetView 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. The skill should use the identifiers here to find the play queue for which Alexa is requesting items. See the ItemReference object for more information. | object |
Example GetView request
When Alexa is playing music from a music skill and the user opens the "Now Playing" screen in the Alexa app, Alexa sends a GetView request like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "GetView",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e710c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"currentItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-9865ce8516f0",
"queueId": "76f325d5-a648-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-9723-067a4338b6d0"
}
}
}
}
Response structure
If the skill can return a list of upcoming items, it should respond with a GetView.Response message.
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 |
GetView.Response |
yes | string |
payloadVersion |
1.0 |
yes | string |
Payload
The following table describes the fields in the payload of a GetView response.
| Field | Description | Required? | Type |
|---|---|---|---|
queueControls |
List of QueueControl objects that Alexa uses to determine which controls to enable in the Alexa app. See the QueueControl object for more information. |
yes | list |
items |
A list of Item objects representing the active queue. The maximum length of the list is ten items. The list should always include the currently playing Item. If the response contains more than ten items, Alexa discards the extra items. For more information, see the Item object. |
yes | list |
Example GetView response
If the skill can return a list of upcoming items, it should respond with a GetView.Response message like the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio.PlayQueue",
"name": "GetView.Response",
"payloadVersion": "1.0"
},
"payload": {
"queueControls": [
{
"type": "TOGGLE",
"name": "SHUFFLE",
"enabled": true,
"selected": false
},
{
"type": "TOGGLE",
"name": "LOOP",
"enabled": true,
"selected": false
}
],
"items": [
{
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"playbackInfo": {
"type": "DEFAULT"
},
"metadata": {
"type": "TRACK",
"name": {
"speech": {
"type": "PLAIN_TEXT",
"text": "alive"
},
"display": "Alive"
},
"art": {
"sources": [
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "X_SMALL",
"widthPixels": 48,
"heightPixels": 48
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "SMALL",
"widthPixels": 60,
"heightPixels": 60
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "MEDIUM",
"widthPixels": 110,
"heightPixels": 110
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "LARGE",
"widthPixels": 256,
"heightPixels": 256
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "X_LARGE",
"widthPixels": 600,
"heightPixels": 600
}
]
}
},
"durationInMilliseconds": 428000,
"controls": [
{
"type": "COMMAND",
"name": "NEXT",
"enabled": true
},
{
"type": "COMMAND",
"name": "PREVIOUS",
"enabled": false
}
],
"rules": {
"feedbackEnabled": true
},
"stream": {
"id": "STREAMID_92_14629004",
"uri": "https://cdn.example.com/api/1/streaming-file.mp3",
"offsetInMilliseconds": 0,
"validUntil": "2018-05-10T19:11:35Z"
},
"feedback": {
"type": "PREFERENCE",
"value": "POSITIVE"
}
},
{
"id": "533718fe-b22d-4f64-8b1c-49ffdb85f619",
"playbackInfo": {
"type": "DEFAULT"
},
"metadata": {
"type": "TRACK",
"name": {
"speech": {
"type": "PLAIN_TEXT",
"text": "porch"
},
"display": "Porch"
},
"art": {
"sources": [
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "X_SMALL",
"widthPixels": 48,
"heightPixels": 48
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "SMALL",
"widthPixels": 60,
"heightPixels": 60
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "MEDIUM",
"widthPixels": 110,
"heightPixels": 110
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "LARGE",
"widthPixels": 256,
"heightPixels": 256
},
{
"url": "https://images.example.com/images/cover/album-art.jpg",
"size": "X_LARGE",
"widthPixels": 600,
"heightPixels": 600
}
]
}
},
"durationInMilliseconds": 449000,
"controls": [
{
"type": "COMMAND",
"name": "NEXT",
"enabled": false
},
{
"type": "COMMAND",
"name": "PREVIOUS",
"enabled": false
}
],
"rules": {
"feedbackEnabled": true
},
"stream": {
"id": "STREAMID_92_14629005",
"uri": "https://cdn.example.com/api/1/streaming-file.mp3",
"offsetInMilliseconds": 0,
"validUntil": "2018-05-10T19:11:35Z"
},
"feedback": {
"type": "PREFERENCE",
"value": "POSITIVE"
}
}
]
}
}
