Alexa Music, Radio, and Podcast Skill API Event Subscriptions
You can configure a music or radio skill to receive notifications when specified events occur. For example, you can create notifications to indicate when a user enables or disables a skill, or when an audio stream fails to play on a device. These notifications are sent to the skill events endpoint to help you evaluate your skill's performance. For example, you can track the number of times your skill is enabled each day.
Skill configuration to support event subscriptions
To configure your skill to support event subscriptions, the skill manifest must include the events.endpoint.uri
field. This field is an AWS Lambda endpoint that accepts events. To update your skill manifest, use the ask deploy command in the Alexa Skills Kit Command Line Interface (ASK CLI). To receive and process events, you can either establish a separate endpoint or use the same Lambda endpoint you use for your skill code.
The events.subscriptions.eventName
field specifies which events you want to receive. These events are categorized as either skill activation events or audio playback events. To review a skill manifest configured to receive event subscriptions, see Example music skill manifest.
Skill activation events
The Alexa Music, Radio, and Podcast Skill API supports the following types of skill activation events. For more information about each event, including the format of its event notifications, see the following documentation.
Audio playback event types
The following table shows the four types of audio playback events that the Alexa Music, Radio, and Podcast Skill API supports.
Event type | Description |
---|---|
Alexa begins playback of an audio stream from the skill. | |
Audio stream finishes playback with no user intervention. | |
Alexa stops playback of an audio stream due to a user action. | |
Alexa encounters an error during initiation or playback of an audio stream. |
The following table shows the structure of an audio playback event message.
Field | Description | Data type |
---|---|---|
|
Event category. The value is always |
string |
|
Unique identifier for the event message. |
string |
|
Date and time at which Alexa sent the request, formatted according to ISO 8601 guidelines. The |
string |
|
Offset of a given track in milliseconds when the event is sent. This field isn't applicable to |
long |
|
Identifier for the item that the device is playing or trying to play. |
object |
The following examples demonstrate the four audio playback event types.
ItemPlaybackStarted
This event occurs when Alexa initiates an audio stream from the skill.
{
"version": "1.0",
"context": {
"System": {
"user": {
"userId": "amzn1.ask.account.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU",
"accessToken": "<accessToken>"
},
"endpointIds": [
"amzn1.ask.device.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU"
]
}
},
"request": {
"requestId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"type": "AlexaAudioPlayQueueEvent.ItemPlaybackStarted",
"timestamp": "2018-04-11T15:15:25Z",
"body": {
"offsetInMilliseconds": 90000,
"item": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
}
}
}
}
ItemPlaybackFinished
An ItemPlaybackFinished
event occurs when the audio stream finishes playback naturally (when a live stream ends, for example, or playback of a three-minute track reaches the three-minute mark), rather than in response to a user's action.
{
"version": "1.0",
"context": {
"System": {
"user": {
"userId": "amzn1.ask.account.AGF3NETIXNZ2ND6TI7A3Q7CO2X4X2HU",
"accessToken": "<accessToken>"
},
"endpointIds": [
"amzn1.ask.device.AGF3NTIE4NXNZ2NDI7A3Q7CO2X4X2HU"
]
}
},
"request": {
"requestId": "3cae4d53-erc2-4f8f-gghj-7dd2727ca84b",
"type": "AlexaAudioPlayQueueEvent.ItemPlaybackFinished",
"timestamp": "2018-09-11T15:15:25Z",
"body": {
"item": {
"id": "e73befbe-8c47-8a8b-ab0c-9865ce8516f0",
"queueId": "queue-ffed55be-4567-1234-45fd-9865ce8556f0",
"contentId": "content123"
}
}
}
}
ItemPlaybackStopped
An ItemPlaybackStopped
event occurs when Alexa stops playback of an audio stream due to a user's action. The following table shows the causes of playback termination.
Cause of event | Description |
---|---|
|
User interrupts playback (for example, "Alexa, stop" or "Alexa, pause"), switches to different content (for example, "Alexa, play 'Ring of Fire'"), or switches to a different music service (for example, "Alexa, play Johnny Cash on Amazon Music"). |
|
User either requests a specific item in the queue or performs a seek operation. To perform a seek operation, the user asks Alexa to move the currently playing item forward or backward (for example, "Alexa, fast forward 10 seconds"), or slides the progress bar on a device with a screen. Note: |
|
User asks for the next item in the queue. |
|
User asks for the previous item in the queue. |
|
User asks Alexa to replay the item. |
|
User asks Alexa to replay the queue. |
{
"version": "1.0",
"context": {
"System": {
"user": {
"userId": "amzn1.ask.account.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU",
"accessToken": "<accessToken>"
},
"endpointIds": [
"amzn1.ask.device.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU"
]
}
},
"request": {
"requestId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"type": "AlexaAudioPlayQueueEvent.ItemPlaybackStopped",
"timestamp": "2018-04-11T15:15:25Z",
"body": {
"offsetInMilliseconds": 100000,
"item": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
},
"playbackAttributes": {
"dataRateInBitsPerSecond": 325461,
"codec": "opus",
"name": "SD",
"sampleRateInHertz": 48000
},
"cause": {
"type": "NEXT"
}
}
}
}
ItemPlaybackFailed
An ItemPlaybackFailed
event type occurs when Alexa encounters an error during initiation or playback of an audio stream. This event type generates an error message to indicate why playback failed. The following table shows the possible reasons for audio playback failure.
Field | Description |
---|---|
|
Unknown error. |
|
Request malformed (for example, bad request, unauthorized, forbidden, or not found). |
|
Unable to reach stream URI. |
|
Unable to process request as expected. |
|
Internal error on device. |
The event generates a message for the error log. Don't use the error message for business logic, because such messages are subject to change.
{
"version": "1.0",
"context": {
"System": {
"user": {
"userId": "amzn1.ask.account.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU",
"accessToken": "<accessToken>"
},
"endpointIds": [
"amzn1.ask.device.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU"
]
}
},
"request": {
"requestId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
"type": "AlexaAudioPlayQueueEvent.ItemPlaybackFailed",
"timestamp": "2018-04-11T15:15:25Z",
"body": {
"offsetInMilliseconds": 90000,
"item": {
"id": "e73befbe-8c27-4e4b-ab0c-9865ce8516f0",
"queueId": "76f325d5-a648-4e8f-87ad-6e53cf99e4c7",
"contentId": "1021012f-12bb-4938-9723-067a4338b6d0"
},
"error": {
"type": "MEDIA_ERROR_UNKNOWN",
"message": "An unknown error occurred."
}
}
}
}
Response
The skill returns an HTTP 200 response as an acknowledgement. Alexa ignores the payload of the response message.
Related topics
- Alexa.Audio.PlayQueue Interface
- Alexa.Media.PlayQueue Interface
- Alexa Music, Radio, and Podcast Skill API Reference Overview
Last updated: Nov 27, 2023