Alexa Music, Radio, and Podcast Skill API Event Subscriptions

Note: Sign in to the developer console to build or publish your skill.

Important: Anyone can build a music skill for public distribution in the United States. However, radio and podcast skills are currently in developer preview. To register your radio or podcast skill for the preview, contact your Alexa Music, Radio, or Podcast representative.

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.

Note: Amazon does not guarantee event notification. Issues such as third-party device errors or loss of internet connectivity can prevent event notification.

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?

Provide feedback

Last updated: Nov 27, 2023