Alexa.Media.PlayQueue GetItem
You can create, develop, enable, test, and submit music skills for certification now, but the Alexa certification team will begin processing and certifying music skills in January 2019. You will receive feedback about the status of your music skill after certification is complete.
If an item's stream URI has expired, Alexa sends a GetItem request to obtain a new (refreshed) URI to begin playback on an Alexa device. This interface is optional. Implement this interface only if the stream URIs returned by your music service cloud can expire.
The primary use case for this API is when an item cached by Alexa is expired and needs to be refreshed. For example, a user is listening to music on their Alexa device, and then says "Alexa, pause". One hour later, the user says "Alexa, resume" but the stream URI for the item is now expired (based on the item's stream.validUntil field). In this scenario, Alexa calls GetItem to receive a new stream URI, and then sends the new stream URI to the device to resume playback.
If your skill does not expire stream URIs, or if the URI expiration period
(stream.validUntil field) is always longer than 24 hours, your skill does not need to support the GetItem API. When a user pauses for an extended period of time (many hours), Alexa eventually forgets about the paused stream. In these cases, when a user later asks "Alexa, resume", Alexa asks the user what she or he would like to hear and then sends new GetPlayableContent and Initiate requests to the skill.
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 GetItem 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 |
GetItem |
string |
payloadVersion |
1.0 |
string |
Payload
The following table describes the fields in the payload of a GetItem request.
| Field | Description | Type |
|---|---|---|
requestContext |
An object containing context information about the request. See the RequestContext object for more information. | object |
targetItemReference |
An object identifying the item to get. See the MediaReference object for more information. | object |
Example GetItem request
Imagine the following scenario: Alexa is playing the first song from a skill's Initiate response. The user pauses playback, then one hour later says "Alexa, resume". The stream URI is now expired, so Alexa will send a GetItem request to obtain a new, non-expired stream URI. See the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.PlayQueue",
"name": "GetItem",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c691234567c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"targetItemReference": {
"namespace": "Alexa.Audio.PlayQueue",
"name": "item",
"value": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
}
}
}
Response structure
When the skill locates the requested item, it sends a GetItem.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 |
GetItem.Response |
yes | string |
payloadVersion |
1.0 |
yes | string |
Payload
The following table describes the fields in the payload of a GetItem response.
| Field | Description | Required? | Type |
|---|---|---|---|
item |
The requested item in the play queue. See the Item object for more information. | yes | object |
Example GetItem response
In response to the preceding example request, the skill returns information about the item identified in the request. See the following example.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Audio.PlayQueue",
"name": "GetItem.Response",
"payloadVersion": "1.0"
},
"payload": {
"item": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"playbackInfo": {
"type": "DEFAULT"
},
"metadata": {
"type": "TRACK",
"name": {
"speech": {
"type": "PLAIN_TEXT",
"text": "Float On"
},
"display": "float on"
},
"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": 208000,
"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"
}
}
}
}
Example ErrorResponse
If the skill cannot find the item identified in the request, it returns a media-specific 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": "The item does not exist"
}
}