Alexa.UserPreference Interface

Implement the Alexa.UserPreference capability interface to enable users to send feedback to your Alexa music skill.

Utterances

When you use the Alexa.UserPreference interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, I like this.
Alexa, I do not like this song.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Configure your skill to receive requests

You must configure your music skill to support this API before Alexa will send requests to it. You can configure your skill in the following ways:

{
    "namespace": "Alexa.UserPreference",
    "requests": [
        {
            "name": "ReceiveFeedback"
        }
    ],
    "version": "2.0"
}

Directives

ReceiveFeedback directive

Alexa sends the ReceiveFeedback request to your skill if a customer gives a negative or positive response while audio is streaming on their device. For example, Alexa sends a ReceiveFeedback request indicating negative feedback if the customer says, Alexa, I don't like this or clicks the "thumbs down" icon in the Alexa app. Similarly, Alexa sends a ReceiveFeedback request indicating positive feedback if a customer says, Alexa, I like this or clicks the "thumbs up" icon in the Alexa app. The following table shows which content types use this directive:

Content type Required?
Music Optional
Radio Optional
Podcast Optional

ReceiveFeedback directive payload details

Field Description Type
requestContext Context information about the request. A RequestContext object.
activeContext A MediaReference object that identifies the song, album, playlist, or station that was playing when the user provided positive or negative feedback. A MediaReference object.
feedback Indicates whether the user is providing positive or negative feedback. A Feedback object.

ReceiveFeedback directive examples

In the following example, the user says, Alexa, I like this song.

{
    "header": {
        "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
        "namespace": "Alexa.UserPreference",
        "name": "ReceiveFeedback",
        "payloadVersion": "2.0"
    },
    "payload": {
        "requestContext" : {
            "user" : {
                "id" : "amzn1.ask.account.AAAAABBBBBCCCCCDDDDDEEEEEFFFFFGGGGGHHHHH",
                "accessToken" : "<an OAuth2 bearer token>"
            },
            "location" : {
                "originatingLocale" : "en-US",
                "countryCode" : "US"
            }
        },
        "activeContext": {
            "content": [
                {
                    "namespace": "Alexa.Audio.PlayQueue",
                    "name": "item",
                    "value": {
                        "id": "d7448db5-6099-40f3-8f74-70897794cae7",
                        "queueId": "75029856-4dc7-442c-8a84-95f327e09ff2",
                        "contentId": "1b3250a0-d2c9-47e9-9892-00845cdfc613",
                    }
                }
            ]
        },
        "feedback": {
            "type": "PREFERENCE",
            "value": "POSITIVE"
        }
    }
}

In the following example, the user says, Alexa, I do not like this.

{
    "header": {
        "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
        "namespace": "Alexa.UserPreference",
        "name": "ReceiveFeedback",
        "payloadVersion": "2.0"
    },
    "payload": {
        "requestContext" : {
            "user" : {
                "id" : "amzn1.ask.account.AAAAABBBBBCCCCCDDDDDEEEEEFFFFFGGGGGHHHHH",
                "accessToken" : "<an OAuth2 bearer token>"
            },
            "location" : {
                "originatingLocale" : "en-US",
                "countryCode" : "US"
            }
        },
        "activeContext": {
            "content": [
                {
                    "namespace": "Alexa.Audio.PlayQueue",
                    "name": "item",
                    "value": {
                        "id": "d7448db5-6099-40f3-8f74-70897794cae7",
                        "queueId": "75029856-4dc7-442c-8a84-95f327e09ff2",
                        "contentId": "1b3250a0-d2c9-47e9-9892-00845cdfc613",
                    }
                }
            ]
        },
        "feedback": {
            "type": "PREFERENCE",
            "value": "NEGATIVE"
        }
    }
}

ReceiveFeedback response event

Your music skill can respond to a ReceiveFeedback directive in one of the following ways:

  • Return a generic Alexa.Response event. The current track continues playing.
  • Return a music-specific Alexa.UserPreference.Audio.ReceiveFeedback.Response event to indicate to Alexa that the currently playing item should be skipped. You can send this response when the user provides negative feedback about the item that's currently playing. This causes the current track to stop, and then Alexa sends a GetNextItem request to the skill.
  • Return an error if the user's access token (accessToken) isn't valid. This only applies to skills that use account linking. See Validate and Use Access Tokens in Music Skill Code.

When your skill can't process the user's feedback for any reason, it should send a generic Alexa.ErrorResponse message with the appropriate error type. See General errors.

Generic response

The payload object in the generic Alexa.Response event is empty.

Generic response example

{
    "header": {
        "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
        "namespace": "Alexa",
        "name": "Response",
        "payloadVersion": "3.0"
    },
    "payload": {
       
    }
}

Music-specific response

When your skill successfully receives the user's feedback, the skill sends an Alexa.UserPreference.Audio.ReceiveFeedback.Response event.

The following table describes the fields in the payload object in the response event.

Field Description Required? Type
skip A flag to indicate whether the currently playing item should be skipped. Yes Boolean

Music-specific response example

When your skill successfully receives the user's negative feedback and the currently playing item should be skipped, the skill sends an Alexa.UserPreference.Audio.ReceiveFeedback.Response event, as in the following example.

{
    "header": {
        "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
        "namespace": "Alexa.UserPreference.Audio",
        "name": "ReceiveFeedback.Response",
        "payloadVersion": "2.0"
    },
    "payload": {
        "skip": true
    }
}
Was this page helpful?

Last updated: Nov 27, 2023