State Reporting for Video Skills

When you implement a video skill, you have the ability to update Alexa on the state of endpoints. Alexa uses this information to provide the best customer experience.

Video skills support change reports, one type of state reporting, to help Alexa know the endpoint that is currently in use. Change reports are events that you send from a video skill to the Alexa event gateway to notify Alexa when certain properties of a video endpoint change for any reason. You do this reporting in addition to the Alexa.Response events you send when your skill receives a directive from Alexa. For example, you use a ChangeReport event to notify Alexa that a customer has turned their video endpoint on, or that the customer has started, stopped or paused media playback, regardless of whether the power or playback state was changed manually or through a voice interaction. For more information about state reporting, see State Reporting For a Smart Home Skill.

Why implement change reports for video skills?

There are multiple reasons to implement change reporting for video skills:

  • Helps ensure Alexa knows the context for best customer experience
  • Enables device routing
  • Creates a better whole-home experience

Customer context

Using change reports helps Alexa set the customer context. Currently the default behavior for Alexa when a customer asks to play content, is to assume the content is music. When you implement change reporting for your video skills, you can notify Alexa that a customer is using a video endpoint, and set the context for requests made to Alexa. This means that requests to play content then default to video content instead of music. For customers, this means Alexa automatically works with music or video content and understands the customer's context.

Device routing & orchestration

Change reports help Alexa know the current endpoint in use. Customers increasingly have multiple video endpoints that work with Alexa in their home. For example, a customer may have a cable box and Fire TV, both of which work with Alexa. Knowing what video endpoint is in use helps ensure that customer requests such as "Alexa, play The Man in the High Castle" go to the right endpoint. Alexa evaluates where the most recent change reports originated from when deciding where to route a directive as a result of a customer request. 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 does not always know where to send directives.

Alexa whole home experience

Change report events 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, if the customer is viewing the home screen on Fire TV, but no media is playing, with change reports, a request like "Alexa, pause" would be routed to pause the music on a audio device playing in another room.

Supported properties and conditions for change reports

You should report when the power state or playback state of a video endpoint has changed. The following table lists the properties, values and change conditions for sending change reports from a video skill.

Property Value Conditions/Actions
powerState ON Endpoint turns on or wakes from sleep
powerState OFF Endpoint turns off or goes to sleep
playbackState PLAYING Customer changes channel, begins video playback or launches an app like Prime Video
playbackState PAUSED Media player paused
playbackState STOPPED Customer exits player and media controls are no longer available. For example, the customer navigates to device home screen or to full screen search results.

Steps to send change reports

The steps to send change reports are outlined below, with links to additional documentation.

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, which will be used 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 will receive an AcceptGrant directive for each customer. The AcceptGrant directive contains an authorization code that you will 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 are handling the AcceptGrant directive, you must respond synchronously with an ErrorResponse event.

For detailed steps to complete this process, see Authenticate a Customer to Alexa with Permissions

Step 3 - Indicate properties are proactively reported during discovery

You must indicate that you will send change reports for an endpoint property during discovery. You do this by indicating the properties are proactivelyReported in your discovery response. For more information, 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

{
    "context": {},
    "event": {
        "header": {
            "messageId": "2b3409df-d686-4a52-9bba-d361860bac61",
            "namespace": "Alexa",
            "name": "ChangeReport",
            "payloadVersion": "3"
        },
         "endpoint": {
           "scope": {
             "type":"BearerToken",
             "token": "access-token-from-Amazon"
           },
           "endpointId": "appliance-001"
         },
            "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PowerController",
                    "name": "powerState",
                    "value": "ON",
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    }
}

Example: change to playbackState

This example ChangeReport for an endpoint that implements the PlaybackStateReporter interface. The event reports that the endpoint changed its playbackState to PLAYING due to a physical interaction with the endpoint, and reports the powerState in the context object, because the powerState did not change.


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

{
    "context": {
        "properties": [{
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        }]
    },
    "event": {
        "header": {
            "messageId": "2b3409df-d686-4a52-9bba-d361860bac61",
            "namespace": "Alexa",
            "name": "ChangeReport",
            "payloadVersion": "3"
        },
        "endpoint": {
          "scope": {
            "type":"BearerToken",
            "token": "access-token-from-Amazon"
          },
          "endpointId": "appliance-001"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PlaybackStateReporter",
                    "name": "playbackState",
                    "value": {
                        "state": "PLAYING"
                    },
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    }
}