Today we’re taking a deep dive into the JSON requests sent to your service each time a user interacts with your skill. Since our technical documentation provides an incredible reference for this JSON file, this post won’t focus as much on the implementation details. Instead, we’re going to highlight how you can use JSON requests to enhance your skills for your customers. But before we get into the specifics, here’s an overview of the entire pipeline that creates this JSON for your skill.

In the diagram above, the user speaks to their device using a wake word like “Alexa.” When the wake word is detected, the light ring around the top of the device turns blue to indicate that Alexa is streaming audio to the cloud, which uses speech recognition and natural language understanding to determine which of the available intents in your skill should be selected. Once this intent has been determined, the Alexa service creates a JSON request that is passed to your backend service. This request contains the name of the intent to be used, as well as additional data like slot values, user ID, and even entity resolution results. 

In the rest of this post, we’re going to take the JSON structure apart, and dig into what each value is, why it is important, and how you might be able to use this information to make your skill more engaging to your users.

A Standard JSON Request

Because of the nature of this JSON data, it can be dramatically different depending on what your user requested, whether there were slot values, and what kinds of capabilities you’re trying to use in your skill. Because of this, we will use the JSON below as our “standard” example, and we will fill in those special conditions as we move through the post.

This example is an “IntentRequest,” which is what happens when the user says something that matches one of your sample utterances for an intent in your skill. This intent also has a custom slot, named “topic,” which allows us to gather some entity resolution data.

{
    "version": "1.0",
    "session": {
        "new": true,
        "sessionId": "amzn1.echo-api.session.768e4e3c-0371-4683-8e11-deb6e5c9704d",
        "application": {
            "applicationId": "amzn1.ask.skill.205357b0-2f92-473c-bd27-9f9193e52c59"
        },
 "attributes": {
            "username": "Jeff Blankenburg"
        },
        "user": {
            "userId": "amzn1.ask.account.AEPVWHXHGCHGQGHMM…"
        }
    },
    "context": {
        "AudioPlayer": {
            "playerActivity": "IDLE"
        },
        "System": {
            "application": {
                "applicationId": "amzn1.ask.skill.205357b0-2f92-473c-bd27…"
            },
            "user": {
                "userId": "amzn1.ask.account.AEPVWHXHGCHGQGHMM…"
            },
            "device": {
                "deviceId": "amzn1.ask.device.AFFQA3N2RLJBGVF…",
                "supportedInterfaces": {
                    "AudioPlayer": {},
			“Display": {
                        "templateVersion": "1.0",
                        "markupVersion": "1.0"
                    },
                    "VideoApp": {}
                }
            },
            "apiEndpoint": "https://api.amazonalexa.com",
            "apiAccessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI…"
        }
    },
    "request": {
        "type": "IntentRequest",
        "requestId": "amzn1.echo-api.request.8fc34805-9fb6-42e2-b785-d527a0e71a5b",
        "timestamp": "2018-02-17T20:10:27Z",
        "locale": "en-US",
        "intent": {
            "name": "AnswerIntent",
            "confirmationStatus": "NONE",
            "slots": {
                "topic": {
                    "name": "topic",
                    "value": "text messaging",
                    "resolutions": {
                        "resolutionsPerAuthority": [
                            {
                                "authority": "amzn1.er-authority.echo-sdk.amzn1.ask.skill.205357b0-2f92-473c-bd27-9f9193e52c59_Live.Topic",
                                "status": {
                                    "code": "ER_SUCCESS_MATCH"
                                },
                                "values": [
                                    {
                                        "value": {
                                            "name": "Text Messaging",
                                            "id": "5ad4bf3d7dd9e2567968d8a239dce2d3"
                                        }
                                    }
                                ]
                            }
                        ]
                    },
                    "confirmationStatus": "NONE"
                }
            }
        }
    }
}

Temporary Updates

Voice is an interesting user interface because you communicate your skill’s information with sound, rather than a display. This means that when you have new content, or new information for your users, you have to find creative ways to communicate that to them.

In the Dev Tips skill, we try to release new features every week. One thing we've focused on is letting our users know that those new features exist. Using the data in our JSON request, we could use the session.new property to determine if this is the first time our user has come back since the updates were included. If it is a new session, you can pair that information with request.timestamp to determine specifically if this user should hear about the new features. You might also want to persist that you have shared this information with your user on a more permanent basis so that you’re not alerting them each time that they start your skill. But this value is a great place to start.

Track User Engagement

To keep track of your users and to know when they return to your skill, you can rely heavily on session.user.userId. This value will be consistent for the same user each time they use your individual skill, but their userId will be anonymized and different in every skill that they use. To identify users across multiple skills, we recommend leaning on something like account linking to manage your users’ preferences.

Take Advantage of Device Context

This isn’t the Device Address API where you can query a user’s device for their address or postal code. This anonymized and unique identifier is context.device.deviceId. It is specific to the device your user is currently speaking to. This allows you to log and identify when a user is using a different device for the same skill. If you prompt the user to identify the location of their device (“kitchen,” for example), you could persist this information, and tailor your conversation and functionality with this context in mind. For example, if you were building a life hacks skill, you might offer hacks for the garage when they are using their garage device, and kitchen hacks when they are using their kitchen device.

In addition to the deviceId, you can also utilize context.device.supportedInterfaces to better serve your user’s needs. This list of supported device interfaces lets you know if their device supports the AudioPlayer, or if the device has a screen, like Echo Show or Echo Spot. If you detect that capability, this means that you can rely on sending Display Directives to the user, which can provide a richer interaction model on those types of devices.

Track Analytics

With every request a user makes of your skill, you have an opportunity to make your skill even better. The key to all of this is to manage and keep track of those requests.

It all starts with request.requestId. This is your anonymized unique identifier for each request that is made of your skill. Pair this with a few more values, and you start to have some rich, useful insights that can help you refine your skill for your customers.

request.timestamp gives you the data you need to track user engagement day-to-day or hour-to-hour.

request.locale is an important value for several reasons.  First, locale allows you to know the selected language and location of your user. So if you are using the same service for all languages of your skill, this locale value allows you to select the appropriate language strings for your user. This can also be an important metric to measure as you are focusing on the future development efforts on your skill. “How many users do we have in the UK?” “We seem to have many requests coming from Germany, perhaps we should invest more time in our German news feature!”

request.intent.name contains the name of the intent in your skill that Alexa matches to the user’s utterance. This provides the insight necessary to determine which portions of your skill are the most popular, or how certain utterances might be landing in the wrong location.

request.intent.slots is the collection of slot values that your user spoke to your skill. By persisting and tracking these values, you can see what your users are asking for, and tweak your slot values or code to better serve those requests in the future. We go through this list every week for the Dev Tips skill to make sure that we have content for all of the topics that users have asked us for.

Build Engaging Skills, Earn Money with Alexa Developer Rewards

Hopefully this overview has sparked a few new ideas about how you can use JSON requests to enhance your skills for your customers.

Every month, developers can earn money for eligible skills that drive some of the highest customer engagement. Developers can increase their level of skill engagement and potentially earn more by improving their skill, building more skills, and making their skills available in in the US, the UK, and Germany. Learn more about our rewards program and start building today.