Alexa.Audio.PlayQueue Interface

Implement the Alexa.Audio.PlayQueue capability interface to enable a voice control experience for your Alexa skill.

Utterances

When you use the Alexa.Audio.PlayQueue interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, next.
Alexa, previous.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Overview

Enforcing skip limits

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. When the request includes \"isUserInitiated\": false, the request should not apply to the user's skip limit because the request was not initiated by the user.

Configure your skill to receive requests

You must configure your music skill to support this API before Alexa will send requests to it. You can configure your skill in the following ways:

Directives

GetNextItem directive

Support the GetNextItem directive so that customers can navigate forward in a content play queue. The following table shows which content types use this directive.

Content type Required?
Music Required
Radio Optional
Podcast Required

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 asks Alexa 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 or program series episode, Alexa tells the user that skipping forward isn't allowed, and the GetNextItem request isn't sent to the skill.

For podcast skills, when the GetNextItem request is initiated by the user (isUserInitiated is true), your skill should return the next newer program. This is true whether the program series is serial or episodic (non-serial). When the GetNextItem request is initiated by Alexa, (isUserInitiated is false), your skill should return the next newer program for a serial program series. It should return the next older program for an episodic program series.

When the currently playing track is part of a subscription play queue, the skill is expected to return the next item to play for a GetNextItem request. The ContentId field in the GetNextItem request object uniquely identifies the subscription play queue. In addition, the following requirements apply:

  • "Play next," "Play next podcast," and "Play next episode" are synonymous. All refer to the next item to play in the subscription play queue.
  • The next item can be from a different podcast if the customer has subscribed to multiple podcasts.
  • The next item should be an episode that the customer hasn't listened to or has only partially listened to.
  • The next item is same whether the request is initiated by the user or by Alexa.
  • Voice navigation should provide the same experience a customer would see navigating the subscription playlist within the provider's app.

The following example shows a customer utterance:

Alexa, next.

GetNextItem directive payload details

Field Description Type
requestContext Context information about the request. A RequestContext object.
currentItemReference The currently playing item. An ItemReference.
isUserInitiated true if the user explicitly asked to skip to the next track (for music) or program (for podcasts), false if the current track or program will soon end and the next item is needed. Boolean

GetNextItem directive Alexa-initiated examples (music)

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.

If the provider supports premium audio (or audio quality streams in addition to the default), the request will also contain an endpoint object which lists the provider's content type identifiers that are playable on the target device. The following example demonstrates support for premium audio.

GetNextItem directive user-initiated example (music)

When the user says, "Alexa, next" while a song is playing, Alexa sends a GetNextItem request as in the following example.

GetNextItem directive Alexa-initiated examples (podcast)

When Alexa needs to get the stream URI for a program to buffer it on the device for a smooth transition, Alexa sends a GetNextItem request as in the following example.

For subscription playback, the payload is identical, except that the content metadataType is PLAYLIST, not PROGRAM.

GetNextItem directive user-initiated examples (podcast)

When the user says, "Alexa, next" while program is playing, Alexa sends a GetNextItem request as in the following example.

For subscription playback, the payload is identical, except that the content metadataType is PLAYLIST, not PROGRAM.

GetNextItem response event

If you handle a GetNextItem directive successfully, respond with an Alexa.Response event.

If your skill has a next item to return, return the next item. If the currently playing item is the last item in the queue, your skill should send "isQueueFinished": true to indicate that there are no more items.

GetNextItem response event payload details

Field Description Type Required
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. Boolean Yes
item The requested item in the play queue. An Item object. Required when isQueueFinished is false.

GetNextItem response examples (music)

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.

In the following example, the skill returns information about the next item that Alexa should play for the user.

The following example adds a background image for Alexa to display while playing the item. For more information, see the background field of the BaseMetadata object.

GetNextItem response examples (podcast)

In the following example, the skill returns information about the next item that Alexa should play for the user.

To disable fast-forward and rewind for a program, respond without the SEEK_ADJUST control as shown in the following example.

When the skill determines that the user has reached their daily skip limit, it returns an error response indicating the error case as shown in the following example.

When the currently playing item is the last item in the queue, the skill returns a response indicating that there are no more programs to return.

GetNextItem directive error handling

If your skill can't handle a GetNextItem directive successfully, it should respond with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses.

Your skill can also reject a user's attempt to skip to the next item when enforcing skip limits.

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": "[MESSAGE_ID]",
    "namespace": "Alexa.Audio",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "SKIP_LIMIT_REACHED",
    "message": "The user has reached their daily skip limit.",
    "retryPeriod": "DAILY"
  }
}

GetPreviousItem directive

Support the GetPreviousItem directive so that customers can navigate backward in a content queue. The following table shows which content types use this directive.

Content type Required?
Music Required
Radio Optional
Podcast Required

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 or podcast episode, Alexa tells the user that skipping back isn't allowed, and the GetPreviousItem request isn't sent to the skill.

For podcast skills, when your skill receives a GetPreviousItem request, your skill should return the next older program. This is true whether the program series is serial or episodic (non-serial).

When the currently playing track is part of a subscription play queue, the skill is expected to return the previous item to play for a GetPreviousItem request. The ContentId field in the GetPreviousItem request object uniquely identifies the subscription play queue. In addition, the following requirements apply:

  • "Play previous," "Play previous podcast," and "Play previous episode" are synonymous. All refer to the previous item to play in the subscription play queue.
  • "Previous item" here refers to the previous episode in the queue and not to an older episode of the podcast.
  • The previous item can be from a different podcast if the customer has subscribed to multiple podcasts.
  • Voice navigation should provide the same experience a customer would see navigating the subscription playlist within the provider's app.

The following example shows a customer utterance:

Alexa, previous.

GetPreviousItem directive payload details

Field Description Type
requestContext Context information about the request. A RequestContext object.
currentItemReference The currently playing item. An ItemReference object.

GetPreviousItem directive examples (music)

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

If the provider supports premium audio (or audio quality streams in addition to the default), the request will also contain an endpoint object which lists the provider's content type identifiers that are playable on the target device. The following example demonstrates premium audio support.

GetPreviousItem directive examples (podcast)

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

For subscription playback, the payload is identical, except that the content metadataType is PLAYLIST, not PROGRAM.

GetPreviousItem response event

If you handle a GetPreviousItem directive successfully, respond with an Alexa.Response event.

GetPreviousItem response event payload details

Field Description Type Required
item The previous item in the play queue. An Item object. Yes

GetPreviousItem response event examples (music)

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

If the provider supports premium audio, then one of the content types in the request will have been selected as the most appropriate type of audio quality to provide to the customer. Whichever is the selected content format should be returned as part of the stream object in the response. Even if the provider selects the default Alexa audio quality for the response, a content format object for that quality should be returned as part of the stream object. The following example demonstrates support for premium audio.

The following example adds a background image for Alexa to display while playing the item. For more information, see the background field of the BaseMetadata object.

GetPreviousItem response event example (podcast)

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

To disable fast-forward and rewind for a program, respond without the SEEK_ADJUST control as shown in the following example.

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 program in a queue, the skill sends an error response as in the following example.

GetPreviousItem directive error handling

If your skill can't handle a GetPreviousItem directive successfully, it should respond with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event. For more information, see Alexa Music, Radio, and Podcast Skill API Error Responses.

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": "[MESSAGE_ID]",
    "namespace": "Alexa.Audio",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "ITEM_NOT_FOUND",
    "message": "There is no previous item."
  }
}

JumpToItem directive

Support the JumpToItem directive so that customers can jump to a specific item in an audio content queue by choosing it in a play queue displayed in the Alexa app. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Not applicable
Podcast Not applicable

Alexa sends a JumpToItem request when audio content is playing from a music skill, and the user views the active queue of music (resulting from a GetView response) in the Alexa app then clicks on a track in the list to play. The skill can return the requested item to play, or return an error if the user can't jump to the selected track because of skip limit enforcement or another reason. The JumpToItem request is similar to the GetNextItem and GetPreviousItem requests, except that instead of moving one position forward or back through the active queue of music, the user jumps directly to the desired position in the queue.

If your skill supports this directive, it must also support the GetView directive.

JumpToItem directive payload details

Field Description Type
requestContext Context information about the request. A RequestContext object.
currentItemReference An object identifying the currently playing item. See the ItemReference object for more information. object
targetItemId The identifier of the item to jump to. String

JumpToItem directive example

In the following example, while listening to the second item in a queue of five items, the user opens the Alexa app and views the active play queue. From there, the user chooses the fifth item in the queue. At that point, Alexa invokes the music skill to jump to the fifth item.

{
    "header": {
        "messageId": "[MESSAGE_ID]",
        "namespace": "Alexa.Audio.PlayQueue",
        "name": "JumpToItem",
        "payloadVersion": "1.0"
    },
    "payload": {
        "requestContext": {
            "user": {
                "id": "amzn1.ask.account.ABCD1234",
                "accessToken": "<accessToken>"
            },
            "location": {
                "originatingLocale": "en-US"
            }
        },
        "currentItemReference": {
            "id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
            "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
            "contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
        },
        "targetItemId": "533718fe-b22d-4f64-8b1c-49ffdb85f619"
    }
}

JumpToItem directive user-initiated example with premium audio

If the provider supports premium audio (or audio quality streams in addition to the default), the request will also contain an endpoint object which lists the provider's content type identifiers that are playable on the target device. The following example demonstrates support for premium audio.

{
  "header": {
    "messageId": "[MESSAGE_ID]",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "JumpToItem",
    "payloadVersion": "1.0"
  },
  "payload": {
    "requestContext": {
      "user": {
        "id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
        "accessToken": "<accessToken>"
      },
      "location": {
        "originatingLocale": "en-US"
      },
      "endpoint": {
        "id": "bi39pe0g5k0pqo42phdtffk7iv8da1bx",
        "players": [
          {
            "playbackMethodType": "ALEXA_AUDIO_PLAYER_QUEUE",
            "id": "AudioPlayer",
            "properties": {
              "supportedContentFormats": [
                {
                  "type": "AUDIO",
                  "contentTypeId": "CT-1234"
                },
                {
                  "type": "AUDIO",
                  "contentTypeId": "CT-1235"
                },
                {
                  "type": "AUDIO",
                  "contentTypeId": "CT-1236"
                }
              ]
            }
          }
        ]
      }
    },
    "targetItemId": "55519bc-b22d-4f64-8b1c-49eegv76f787",
    "currentItemReference": {
      "id": "533718fe-b22d-4f64-8b1c-49ffdb85f619",
      "queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
      "content": {
        "id": "1021012f-12bb-4938-9723-067a4338b6d0",
        "metadataType": "TRACK"
      }
    }
  }
}

JumpToItem response event

If the requested item is valid and the jump is allowed, respond with a JumpToItem.Response event. The response header contains the common response header fields.

JumpToItem response event payload details

Field Description Type Required
item The requested item in the play queue. An Item object. Yes

JumpToItem response event examples

In response to the preceding example request, the skill returns information about the item identified in the request, as shown in the following example.

If the provider supports premium audio, then one of the content types in the request will have been selected as the most appropriate type of audio quality to provide to the customer. Whichever is the selected content format should be returned as part of the stream object in the response. Even if the provider selects the default Alexa audio quality for the response, a content format object for that quality should be returned as part of the stream object. The following example demonstrates support for premium audio.

The following example adds a background image for Alexa to display while playing the item. For more information, see the background field of the BaseMetadata object.

JumpToItem directive error handling

If your skill can't handle a JumpToItem directive successfully, it should respond with an Alexa.Media.ErrorResponse event or an Alexa.ErrorResponse event.

Your skill can enforce skip limits by returning a SKIP_LIMIT_REACHED error when the user tries to jump after having reached their skip limit. See Alexa Music, Radio, and Podcast Skill API Error Responses.

JumpToItem response error handling example

In this example the music skill has called GetView and displayed a list of items to the user in the Alexa app. The user chooses one of the items from the list, causing Alexa to send a JumpToItem request. Between the GetView call and the JumpToItem call, the skill has updated the playlist, causing the jump target to be no longer valid. The skill should return the following error response.

{
    "header": {
        "messageId": "[MESSAGE_ID]",
        "namespace": "Alexa.Media",
        "name": "ErrorResponse",
        "payloadVersion": "1.0"
    },
    "payload": {
        "type": "INVALID_ITEM",
        "message": "The requested item is no longer valid."
    }
}
Was this page helpful?

Last updated: Nov 27, 2023