Alexa.Audio.PlayQueue GetPreviousItem

Alexa sends a GetPreviousItem request to the skill when a content queue exists and playback has started on the Alexa device, and one of the following is true:

  • The user asks Alexa to skip back to the previous item.
  • The user chooses to skip back to the previous item (for example, in the Alexa app).

Alexa sends a GetPreviousItem request only when the currently playing item has the PREVIOUS control enabled, indicating that the user can skip backwards.

For example, when a user is listening to the fourth track from an album and asks Alexa to skip back, Alexa sends a GetPreviousItem request to the skill. The skill should respond with the third track from the album, which Alexa then plays on the device.

When the currently playing track has the PREVIOUS control disabled and the user asks Alexa for the previous song, Alexa tells the user that skipping back is not allowed, and the GetPreviousItem request is not sent to the skill.

With the GetPreviousItem 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. The skill can optionally return an error response indicating that the user has reached the skip limit.

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

Payload

The following table describes the fields in the payload of a GetPreviousItem 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

Example GetPreviousItem requests

When a user says "Alexa, previous" while listening to a song in a queue, Alexa sends a GetPreviousItem request as in the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetPreviousItem",
    "payloadVersion": "1.0"
  },
  "payload": {
    "requestContext": {
      "user": {
        "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
        "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
      },
      "location": {
        "originatingLocale": "en-US"
      }
    },
    "currentItemReference": {
      "id": "533718fe-b22d-4f64-8b1c-49ffdb85f619",
      "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
      "content": {
        "id": "1021012f-12bb-4938-9723-067a4338b6d0",
        "metadataType": "TRACK"
      }
    }
  }
}

Response structure

When the skill has a previous item to return, it should respond with a GetPreviousItem.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 GetPreviousItem.Response yes string
payloadVersion 1.0 yes string

Payload

The following table describes the fields in the payload of a GetPreviousItem response.

Field Description Required? Type
item The previous item in the play queue. See the Item object for more information. yes object

Example GetPreviousItem responses

When the skill has a previous item to return, it respond with a GetPreviousItem.Response as in the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetPreviousItem.Response",
    "payloadVersion": "1.0"
  },
  "payload": {
    "item": {
      "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
      "playbackInfo": {
        "type": "DEFAULT"
      },
      "metadata": {
        "type": "TRACK",
        "name": {
          "speech": {
            "type": "PLAIN_TEXT",
            "text": "come as you are"
          },
          "display": "Come As You Are"
        },
        "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": 218000,
      "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-11-10T19:11:35Z"
      },
      "feedback": {
        "type": "PREFERENCE",
        "value": "POSITIVE"
      }
    }
  }
}

When there is no previous item to return, the skill should respond with an ErrorResponse of type ITEM_NOT_FOUND. For example, when the user says "Alexa, previous" while listening to the first track in a queue, the skill sends an error response as in the following example.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "ITEM_NOT_FOUND",
    "message": "There is no previous item."
  }
}