State Reporting for Video Skills

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

When you create an Alexa video skill that interacts with a smart home device, you can include support for state and change reporting. Alexa notifies users about the state of their devices by voice response or in the Alexa app.

You report state to Alexa in three ways:

Alexa requests the state with an Alexa.ReportState directive. For example, a customer opens the Alexa app to see if the TV is on. You reply with an Alexa.StateReport that includes a snapshot of all property values.
You proactively send an Alexa.ChangeReport event to indicate one or more of the properties that changed. In the event, you also include a snapshot of all other property values. For example, the customer launches a video. In the event, you report the power is on and the endpoint is connected.
You proactively send the state of all properties in a directive Alexa.Response. For example, when you respond to a Play directive, you include a snapshot of all property values.

For details about state reporting, see Understand State and Change Reporting.

Why implement change reports for video skills?

Video skills use change reporting to help Alexa know the endpoint that's currently in use. For example, you use a ChangeReport event to notify Alexa that a user has turned their video endpoint on, or that the user has started, stopped or paused media playback. You send the change report regardless of whether the power or playback state was changed manually or through a voice interaction. Alexa sets the context for future requests for a better customer experience.

Implement change reporting in your video skill to set context, enable device routing, and create a whole-home experience.

Context

When a user asks Alexa to play content, the default behavior for Alexa is to assume that the content is music. When your skill sends a change report to notify Alexa that a user is using a video endpoint, Alexa sets the context for future requests. Then, when the user asks Alexa to play content, Alexa defaults to video content instead of music. For customers, this means Alexa understands the customer's context and works with music or video content automatically.

Device routing and orchestration

Customers increasingly have multiple video endpoints that work with Alexa in their home. For example, a customer might have a cable box and Fire TV that both work with Alexa. When Alexa knows the video endpoint that's in use, user requests, such as, "Alexa, play the Man in the High Castle", go to the right endpoint. To route the directive, Alexa evaluates the most recent change reports to decide which endpoint to use. For example, if customer is using the cable box, "Play The Man in the High Castle" is sent to the skill that controls the box. If a customer then switches to Fire TV, the directive as a result of the request to "Play The Man in the High Castle" is sent to the Fire TV skill. Without change reports, Alexa doesn't always know where to send directives.

Alexa whole home experience

Change reports help Alexa know whether a customer's request is meant for a video endpoint or one of potentially multiple other endpoints in the home, such as smart speakers or a whole home audio system. For example, a customer is viewing the home screen on Fire TV, but no media is playing. Because a skill reports updates with change reports, Alexa routes requests, such as, "Alexa, pause", to the audio device playing music in another room.

Video skill properties

The following table lists some of the properties, values, and change conditions for sending change reports from a video skill. For details about properties, see the documentation for the interface that your skill supports.

Property	Value	Conditions
`powerState`	ON	Endpoint turns on or wakes from sleep.
`powerState`	OFF	Endpoint turns off or goes to sleep.
`playbackState`	PLAYING	User changes channel, begins video playback, or launches an app, such as Prime Video.
`playbackState`	PAUSED	User pauses the endpoint.
`playbackState`	STOPPED	User stops video playback, navigates to the device home screen, or views full-screen search results.

Send change report events

You send Alexa.ChangeReport events to the Alexa event gateway directly from your device cloud or Lambda function. This message flow requires that you enable events in the Alexa developer console and obtain access tokens for each customer. For detailed steps to enable asynchronous events in your code, see Send Events to the Alexa Event Gateway.

Change report example

The following example shows a ChangeReport event for an endpoint that implements the Alexa.PlaybackController interface. The event reports that the endpoint changed its playbackState to STOPPED due to a physical interaction with the endpoint.

POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer {access-token-from-Amazon}
Content-Type: application/json

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PlaybackStateReporter",
                    "name": "playbackState",
                    "value": {
                        "state": "STOPPED"
                    },
                    "timeOfSample": "2021-12-01T18:20:00.00Z",
                    "uncertaintyInMilliseconds": 500
                }]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-12-01T18:00:00.00Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

Was this page helpful?

Provide feedback

Last updated: Aug 23, 2024