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"
        }
      }
    ]
  }
}