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

ItemPlaybackStarted

Alexa begins playback of an audio stream from the skill.

ItemPlaybackFinished

Audio stream finishes playback with no user intervention.

ItemPlaybackStopped

Alexa stops playback of an audio stream due to a user action.

ItemPlaybackFailed

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

type

Event category. The value is always AlexaAudioPlayQueueEvent, followed by a period (.) and one of a the four event types shown in the preceding table.

string

requestId

Unique identifier for the event message.

string

timestamp

Date and time at which Alexa sent the request, formatted according to ISO 8601 guidelines. The timestamp is determined by the Alexa service, not by the device.

string

body.offsetInMilliseconds

Offset of a given track in milliseconds when the event is sent. This field isn't applicable to ItemPlaybackFinished events.

long

body.item

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

STOP

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").

JUMP

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: JUMP is not supported for podcasts.

NEXT

User asks for the next item in the queue.

PREVIOUS

User asks for the previous item in the queue.

RESTART_ITEM

User asks Alexa to replay the item.

RESTART_QUEUE

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

MEDIA_ERROR_UNKNOWN

Unknown error.

MEDIA_ERROR_INVALID_REQUEST

Request malformed (for example, bad request, unauthorized, forbidden, or not found).

MEDIA_ERROR_SERVICE_UNAVAILABLE

Unable to reach stream URI.

MEDIA_ERROR_INTERNAL_SERVER_ERROR

Unable to process request as expected.

MEDIA_ERROR_INTERNAL_DEVICE_ERROR

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.


Was this page helpful?

Last updated: Nov 27, 2023