State Reporting for Video Skills

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 the properties, values, and change conditions for sending change reports from a video skill.

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.

Steps to send change reports

Follow these steps to send change reports to Alexa from your video skill.

Step 1 - Request permission to send events

ChangeReports events are sent to the Alexa event gateway, which requires an authentication token for each customer. In the developer console, find your skill, and select Send Alexa Events in the PERMISSION section. Remember to record your Client ID and Client Secret. You use these in the next step to authenticate the customer with Login with Amazon (LWA).

Step 2 - Add code to handle AcceptGrant directives

When you request permission to send Alexa events, your skill's Lambda function receives an AcceptGrant directive for each customer. The AcceptGrant directive contains an authorization code that you use to obtain an authentication token for the customer. You must add code to obtain and store the tokens in the same region where your customer is located. If the AcceptGrant directive was successfully handled, respond with an AcceptGrant.Response event. If an error occurs while you're handling the AcceptGrant directive, you must respond synchronously with an ErrorResponse event.

For detailed steps to complete this process, see Request Access to the Alexa Event Gateway

Step 3 - Indicate properties are proactively reported during discovery

You must indicate that you send change reports for an endpoint property during discovery. You do this by indicating the properties are proactivelyReported in your discovery response. For details, see State Reporting for a Smart Home Skill

Step 4 - Send change report events to the Alexa event gateway

The final step is to begin sending change reports to the event gateway when a reportable property changes. This means that when an a powerState or playbackState property changes for any reason, send a ChangeReport event, which includes the current state of the property to the Alexa event gateway. Each message to the event gateway should include the authentication token as an HTTP header and in the body of the message.

For details about how and where to send a change report and the format for change reports, see Send Events to the Alexa Event Gateway.

Example: change to powerState

This example ChangeReport event is for an endpoint that implements the Alexa.PowerController interface. The event reports that the endpoint changed its powerState from OFF to ON 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": "a unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 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:50Z",
                    "uncertaintyInMilliseconds": 500
                }]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2021-12-01T18:20:50Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}