Alexa.Media.Playback Initiate
When Alexa receives a content identifier from a skill's GetPlayableContent response and is ready to start immediate playback of the content on an Alexa device, Alexa sends an Initiate
request. The request includes the content identifier, and the skill responds with the stream URI for immediate playback of the content.
There are three primary scenarios that cause Alexa to call this API:
- The user requested music or radio to play, so playback is initiated immediately.
- A previously set music alarm is triggered. For example, the user set an alarm to play a song at 7:00 AM, so at that time Alexa makes an
Initiate
call to the skill. - The user selects content from a play history UI that shows (for example in the Alexa app, or on an Alexa device with a screen) to hear the content again.
Understand ContentId
To build a high quality music skill, you must understand ContentId
. ContentId
identifies a music listening experience that a skill can return and play on a device. A ContentId
can reference a track, an editorial playlist of popular songs, a custom (artist or genre seeded) station, or an album.
ContentId
must be globally unique within your skill, long-lived, and always represent the same experience for all skill users. For example, imagine that Alice asks "Alexa, play the album Rainier Fog by Alice in Chains", and the skill returns a ContentId
of "123" to represent the album. This same ContentId
should represent this album for all users. When Bob asks "Alexa, play the album Rainier Fog by Alice in Chains", your skill should send the same ContentId
of "123" in response to the GetPlayableContent
request, even if the request happens one year after Alice's request.
Here is another example: Imagine that your music service has a "Top Weekly Songs" playlist, where the list of songs in the playlist changes from week to week to reflect the most popular songs on the charts. Alice asks "Alexa, play the top weekly songs playlist". Your skill responds with a ContentId
of "321" which represents the "Top Weekly Songs" playlist. When Alexa sends this ContentId
in an Initiate
request, your skill returns the first track of the playlist, for example Shallow by Lady Gaga. One month later, Alice asks "Alexa, play the top weekly songs playlist". Your skill again responds with a ContentId
of "321" because this ContentId
always represents the "Top Weekly Songs" playlist. However, this time when Alexa sends this ContentId
in an Initiate
request, your skill returns, for example, the song Better Now by Post Malone, because the playlist contents change weekly.
ContentId
must be immutable.When a user sets a music alarm (for example, "Alexa, wake me up to Can't Stop The Feeling by Justin Timberlake from skill name at 8 AM"), Alexa saves the ContentId
returned in the GetPlayableContent
response. Each time the alarm is triggered, which might be months later for a repeating alarm, Alexa sends an Initiate
request to your skill with the saved ContentId
, and the response should reflect the content the user requested when setting the alarm.
Similarly, when a user browses their history of music requests and selects an item to replay, Alexa calls Initiate
with the saved ContentId
. In the preceding example for "Top Weekly Songs", if the user sees "Top Weekly Songs" in their history and clicks to play it again, Alexa sends an Initiate
request with a ContentId
of "321". The resulting queue of songs might be different because the playlist changes weekly, but the user is still listening to the "Top Weekly Songs" playlist, so the result is correct.
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 an Initiate
request.
Header
For an overview of the header format, see message header.
Field | Value | Type |
---|---|---|
messageId |
A version 4 UUID | string |
namespace |
Alexa.Media.Playback |
string |
name |
Initiate |
string |
payloadVersion |
1.0 |
string |
Payload
The following table describes the fields in the payload of an Initiate
request.
Field | Description | Type |
---|---|---|
requestContext |
An object containing context information about the request. See the RequestContext object for more information. | object |
filters |
Filters to apply during content resolution. See the Filters object for more information. | object |
contentId |
Identifies the content to use for creating a playback queue. | string |
currentItemReference |
An identifier for the item that is currently playing (active) on the target endpoint, if any. See the MediaReference object for more information. Note that this property is absent when nothing is playing. Your skill should use this property to enforce concurrency limits. More specifically, you can use it to determine whether the playback session will start on an endpoint where no stream is playing, or it will replace an existing stream on an endpoint. | object |
playbackModes |
An object describing the playback mode requirements. See the PlaybackModesCriteria object for more information. If the user did not mention anything about a looped or shuffled queue, this attribute defaults to false for all supported playback modes. |
object |
PlaybackModesCriteria structure
Property | Description | Type |
---|---|---|
shuffle |
A flag that indicates whether the user asked for the queue to be shuffled, for example "Alexa, shuffle the album Gemini by Macklemore". | Boolean |
loop |
A flag that indicates whether the user asked for the queue to be looped, for example "Alexa, loop the album Gemini by Macklemore". | Boolean |
Example Initiate requests
Imagine that a user said "Alexa, play the song Jeremy by Pearl Jam." The skill returned a valid response (containing a content reference) to the GetPlayableContent
API. Alexa decides to play the content from that response. To start playback, Alexa sends an Initiate
request, similar to the following example, instructing the skill to create a queue from the content reference.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.Playback",
"name": "Initiate",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"filters": {
"explicitLanguageAllowed": true
},
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0",
"playbackModes": {
"shuffle": false,
"loop": false
}
}
}
The following example demonstrates the case where a user requests content (similar to the preceding example), but the user is already listening to music from the skill on the target device. In this case, Alexa exposes this information in the request, as shown in the following example (see currentItemReference
).
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.Playback",
"name": "Initiate",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"filters": {
"explicitLanguageAllowed": true
},
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0",
"currentItemReference": {
"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"
}
},
"playbackModes": {
"shuffle": false,
"loop": false
}
}
}
The following example demonstrates the request that occurs when a user requests to shuffle content, for example "Alexa, shuffle songs by Lady Gaga."
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.Playback",
"name": "Initiate",
"payloadVersion": "1.0"
},
"payload": {
"requestContext": {
"user": {
"id": "amzn1.ask.account.AGF3NETIE4MNXNG2Z64Z27RXB6JCK2R62BCPYUZI",
"accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
},
"location": {
"originatingLocale": "en-US"
}
},
"filters": {
"explicitLanguageAllowed": true
},
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0",
"playbackModes": {
"shuffle": true,
"loop": false
}
}
}
Response structure
You skill's response to the Initiate
request contains the information necessary to begin audio playback on the user's target device.
Header
For an overview of the header format, see message header.
Field | Value | Required? | Type |
---|---|---|---|
messageId |
A version 4 UUID | yes | string |
namespace |
Alexa.Media.Playback |
yes | string |
name |
Initiate.Response |
yes | string |
payloadVersion |
1.0 |
yes | string |
Payload
The following table describes the fields in the payload of an Initiate
response.
Field | Description | Required? | Type |
---|---|---|---|
playbackMethod |
A polymorphic object containing information about the playback method that Alexa should use to achieve playback for the user. See the PlaybackMethod object for more information. | yes | object |
Example Initiate response
In response to the first of the preceding examples, the skill creates a queue for the user based on the requested ContentId
and returns the queue identifier and the first audio item to Alexa. The Initiate response should contain enough information for Alexa to know how to manage the queue, and the first track to play for the user. To get the second track to play for the user, Alexa makes an additional call after beginning to play the first track.
{
"header": {
"messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"namespace": "Alexa.Media.Playback",
"name": "Initiate.Response",
"payloadVersion": "1.0"
},
"payload": {
"playbackMethod": {
"type": "ALEXA_AUDIO_PLAYER_QUEUE",
"id": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"controls": [
{
"type": "TOGGLE",
"name": "SHUFFLE",
"enabled": true,
"selected": false
},
{
"type": "TOGGLE",
"name": "LOOP",
"enabled": true,
"selected": false
}
],
"rules": {
"feedback": {
"type": "PREFERENCE",
"enabled": true
}
},
"firstItem": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"playbackInfo": {
"type": "DEFAULT"
},
"metadata": {
"type": "TRACK",
"name": {
"speech": {
"type": "PLAIN_TEXT",
"text": "jeremy"
},
"display": "Jeremy"
},
"art": {
"sources": [
{
"url": "https://example.com/images/cover/48x48-000000-80-0-0.jpg",
"size": "X_SMALL",
"widthPixels": 48,
"heightPixels": 48
},
{
"url": "https://example.com/images/cover/60x60-000000-80-0-0.jpg",
"size": "SMALL",
"widthPixels": 60,
"heightPixels": 60
},
{
"url": "https://example.com/images/cover/110x110-000000-80-0-0.jpg",
"size": "MEDIUM",
"widthPixels": 110,
"heightPixels": 110
},
{
"url": "https://example.com/images/cover/256x256-000000-80-0-0.jpg",
"size": "LARGE",
"widthPixels": 256,
"heightPixels": 256
},
{
"url": "https://example.com/images/cover/600x600-000000-80-0-0.jpg",
"size": "X_LARGE",
"widthPixels": 600,
"heightPixels": 600
}
]
}
},
"durationInMilliseconds": 318000,
"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/a2f318467fbf2829996adc0880e0abd03d03b1ba6ac.mp3",
"offsetInMilliseconds": 0,
"validUntil": "2018-05-10T19:11:35Z"
},
"feedback": {
"type": "PREFERENCE",
"value": "POSITIVE"
}
}
}
}
}
Response performance requirements
A skill's response times to an Initiate
request directly impact the Alexa user experience. A music skills should adhere to the following limits. Longer response times might result in your skill failing certification.
Call Percentage | Latency Limit (in milliseconds) |
---|---|
50% | 100 ms |
90% | 250 ms |
99% | 400 ms |