Alexa Music Skill API Event Subscriptions

You can configure a music skill to receive notifications when various events occur. For example, when a user enables or disables the skill, or when an audio stream fails to play on a device, you can elect to receive a message sent to your skill events endpoint. You can log these messages for analytics purposes, such as tracking how many times your skill is enabled on a daily basis.

Configure a skill to receive events

To configure a skill to receive events, you update the skill manifest to support event subscriptions, then use the ask deploy command in the ASK CLI to enable event subscriptions for a skill. In the skill manifest, you provide an AWS Lambda endpoint (via the events.endpoint.uri field) that can receive the events, and then identify which events (via the events.subscriptions.eventName field) you want to receive. You can use the same Lambda endpoint for events as for your skill code, or a different Lambda endpoint dedicated to receiving and processing events. For an example skill manifest that's configured to receive event subscriptions, see example music skill manifest.

There are two types of events that you can receive:

Skill activation events

The Alexa Music Skill API supports the following types of skill activation events. For more information about each, including the format of the event messages, see the linked documentation in the following list.

Audio playback events

The Alexa Music Skill API supports the following types of audio playback events.

  • ItemPlaybackStarted – Sent when Alexa begins playing an audio stream from the skill. This indicates that playback began.
  • ItemPlaybackFinished – Sent when the audio stream finishes playing naturally.
  • ItemPlaybackStopped – Sent when Alexa stops playing an audio stream due to a user action.
  • ItemPlaybackFailed – Sent when Alexa encounters an error while attempting to initiate a stream, or during playback.

The following table describes the structure of an audio playback event message.

Field Description Type
type The type of event. This value is always AlexaAudioPlayQueueEvent followed by one of the following:
.ItemPlaybackStarted
.ItemPlaybackFinished
.ItemPlaybackStopped
.ItemPlaybackFailed
string
requestId A unique identifier for the event message. string
timestamp The date and time when Alexa sent the request, as an ISO 8601 formatted string. The timestamp is determined by the Alexa service, not by the device. string
body.offsetInMilliseconds Identifies a track's offset in milliseconds when the event is sent. This field is not sent for ItemPlaybackFinished events. long
body.item An identifier for the item that the device was playing or attempting to play. object

Audio playback event examples

The following sections contain examples that demonstrate the format of audio playback events.

ItemPlaybackStarted example

Sent when Alexa begins playing an audio stream from the skill. This indicates that playback began.

{
  "version": "1.0",
  "context": {
    "System": {
      "user": {
        "userId": "amzn1.ask.account.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU",
        "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
      },
      "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 example

Sent when the audio stream finishes playing naturally, rather than a user triggering the stream to stop. For example, playback of a three minute track has reached the three minute mark, or a live stream has ended.

{
  "version": "1.0",
  "context": {
    "System": {
      "user": {
        "userId": "amzn1.ask.account.AGF3NETIXNZ2ND6TI7A3Q7CO2X4X2HU",
        "accessToken": "e72e16c7e42f912e7710c88347ae178b4a"
      },
      "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 example

Sent when Alexa stops playing an audio stream due to a user action. This event indicates the reason why Alexa stopped playing the audio via one of the following cause types:

  • STOP – Indicates that the event was because the user interrupted playback (for example, by saying "Alexa, stop" or "Alexa, pause"), switched to different content (for example, by saying "Alexa, play Twenty One Pilots"), or switched to a different music service (for example, by saying "Alexa, play The Decemberists on Amazon Music").
  • JUMP – Indicates that the event was because the user requested a specific item in the queue.
  • NEXT – Indicates that the event was because the user requested the next item in the queue.
  • PREVIOUS – Indicates that the event was because the user requested the previous item in the queue.
  • RESTART_ITEM – Indicates that the event was because the user requested to replay the item.
  • RESTART_QUEUE – Indicates that the event was because the user requested to replay the queue.
{
  "version": "1.0",
  "context": {
    "System": {
      "user": {
        "userId": "amzn1.ask.account.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU",
        "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
      },
      "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"
      },
      "cause": {
        "type": "NEXT"
      }
    }
  }
}

ItemPlaybackFailed example

Sent when Alexa encounters an error while attempting to initiate a stream, or during playback. This event indicates the reason why Alexa stopped playing the audio via one of the following error types:

  • MEDIA_ERROR_UNKNOWN – An unknown error occurred.
  • MEDIA_ERROR_INVALID_REQUEST – Alexa recognized that the request was malformed. For example, a bad request, unauthorized, forbidden, not found, etc.
  • MEDIA_ERROR_SERVICE_UNAVAILABLE – Alexa was unable to reach the URI for the stream.
  • MEDIA_ERROR_INTERNAL_SERVER_ERROR – Alexa accepted the request, but was unable to process the request as expected.
  • MEDIA_ERROR_INTERNAL_DEVICE_ERROR – There was an internal error on the device.

The event can also contain an error message, which is a description of the error for logging purposes. Don't use the error message for business logic because the error messages are subject to change.

{
  "version": "1.0",
  "context": {
    "System": {
      "user": {
        "userId": "amzn1.ask.account.AGF3NETIE4MNXNZ2ND6TI7A3Q7CO2X4X2HU",
        "accessToken": "e72e16c7e42f292c6912e7710c838347ae178b4a"
      },
      "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 should return an HTTP 200 response as an acknowledgement. Alexa ignores the payload of the response message.