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 NEXT control 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 GetNextItem because 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.

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
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment