Alexa.ChangeReport Interface 3

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

Implement the Alexa.ChangeReport event in your skill to report proactively a property update to Alexa. For example, a customer might manually turn on the light. You send a change report so that Alexa displays the correct status of the light in the Alexa app.

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

Important: To provide the best experience for the user, Amazon recommends that you send change reports from your skill for most devices and interfaces. Exceptions include low-energy devices that are normally in a dormant state, infrared transmitters, and others.

For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Discovery

During discovery, you identify the interfaces that your skill supports and the reportable properties of each interface. When you set proactivelyReported = true for an interface, your skill sends an Alexa.ChangeReport event to Alexa when any property of that interface changes.

Discover response example

The following example shows a Discover.Response message for an Alexa skill that controls a light and supports the Alexa.PowerController, Alexa.BrightnessController, and Alexa.EndpointHealth interfaces. The powerState, brightness, and connectivity properties are reportable.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint of the light ",
                "manufacturerName": "Manufacturer of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Living Room Light",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.BrightnessController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "brightness"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Change reporting

You send an Alexa.ChangeReport event to report changes proactively in the state of an endpoint. If you specify the properties of an interface as proactivelyReported during discovery, you must send Alexa an Alexa.ChangeReport event whenever a property value changes. If a state change happens because of a directive from Alexa, you send both a directive response and a change report event. You send Alexa.ChangeReport events asynchronously to the Alexa event gateway.

To let Alexa know the health of your device, include Alexa.EndpointHealth in the event.

Important: To send Alexa.ChangeReport events, request permission to send events to the Alexa event gateway and obtain authentication tokens for each customer. You include the token in the scope of the event message. For details, see Request Access to the Alexa Event Gateway.

ChangeReport event example

The following example shows an Alexa.ChangeReport event that your skill sends to Alexa proactively. The endpointId identifies the device and the scope identifies the customer. In the example, the skill reports that the powerState property changed to ON due to physical interaction with the device. You also include the state of the unchanged properties in the context object.

Copied to clipboard.

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": "access-token-from-Amazon"
            },
            "endpointId": "endpoint id of the light"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.PowerController",
                    "name": "powerState",
                    "value": "ON",
                    "timeOfSample": "2022-02-03T08:10:00.10Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2022-02-01T08:00:00.10Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2022-02-03T08:00:00.10Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

ChangeReport event properties

Property	Description	Type	Required
`event`	Identifies the customer and endpoint for the report. The payload includes the new property value and the reason for the change. You must include at least one property in the `payload` object.	`Event` object	Yes
`context`	Report the state of all other reportable properties. List these properties and their values in the `properties` array.	`Context` object	Yes

Payload object

The Payload object includes the reason that the skill reports a change and the list of changed property values. To include a property, you must define the property as proactivelyReported = true in your discovery response. You include only property values that changed in the Payload object.

Important: Only specify the value for a property in one place in an event, either the payload or the context, but not both.

Property	Description	Type	Required
`change`	Identifies the details of the change.	Object	Yes
`change.cause`	Reason for the change in one or more properties.	`Cause` object	Yes
`change.properties`	List of properties that changed. Include one object for each property that changed.	Array of `Property` objects	Yes

Cause object

The following table shows the Cause object properties.

Property	Description	Type	Required
`type`	Identifies what caused the change.	`Type` string	Yes

Type values

Use one of the following type values to describe the reason that the property value changed.

Cause type	Description
`APP_INTERACTION`	Customer interaction with a device app. For example, a customer switches on a light or locks a door by using an app provided by the device vendor.
`PERIODIC_POLL`	Periodic poll of an endpoint. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa.
`PHYSICAL_INTERACTION`	Physical interaction with an endpoint. For example, the user turned on a light or locked a door lock manually.
`VOICE_INTERACTION`	Any user interaction with Alexa. For example, a user turns on a light by speaking to their Echo device, or a user turns off the light by using their Alexa app.

ChangeReport response

On success, Alexa sends 202 Accepted to indicate that the event was accepted for further logical validation and processing. If the event isn't accepted, Alexa sends the appropriate HTTP status code.

Response body parameters

This response has no body.

HTTP status codes

The following table shows the HTTP status code values that your skill might receive from the Alexa event gateway. If you receive an error, the payload object contains a code and description field. Use these fields for logging only.

Status	Payload code	Description
`202 Accepted`	—	Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing.
`400 Bad Request`	`INVALID_REQUEST_EXCEPTION`	Message is invalid due to missing fields, incorrect values, or malformed JSON. Check your messages against the documentation to verify that your message contains all the required fields.
`401 Unauthorized`	`INVALID_ACCESS_TOKEN_EXCEPTION`	Message didn't include the authorization token or the token is invalid, expired, or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. Here, the user revoked authorization, and you can stop sending change reports for them.
`403 Forbidden`	`SKILL_NEVER_ENABLED_EXCEPTION`	You're not allowed access to the event gateway. Make sure that you're sending the events to the correct regional endpoint. For example, send events in North America to the North American endpoint.
`403 Forbidden`	`INSUFFICIENT_PERMISSION_EXCEPTION`	Token doesn't have the required permissions. Make sure that the skill has permission to send Alexa events. For details, see Request Access to the Alexa Event Gateway.
`404 Not Found`	`ACCOUNT_NOT_FOUND_EXCEPTION`	Account record associated with this directed identifier doesn't exist or has expired. This error can occur if the event was sent too late or with an invalid directed identifier. Verify that the directed identifier and authorization code are correct.
`404 Not Found`	`SKILL_NOT_FOUND_EXCEPTION`	Skill ID associated with this token wasn't found. This error occurs when user's access token was generated when the skill was in different stage, such as certification. Try disabling and re-enabling the skill for this user.
`413 Payload Too Large`	`REQUEST_ENTITY_TOO_LARGE_EXCEPTION`	Size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send your message with smaller payloads.
`429 Too Many Requests`	`THROTTLING_EXCEPTION`	Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt.
`500 Internal Server Error`	`INTERNAL_SERVICE_EXCEPTION`	Error occurred with Alexa, and the message wasn't processed. Resend the message up to three times, with at least a one-second interval between each send attempt. If problems persist, contact Amazon Support.
`503 Service Unavailable`	`SERVICE_UNAVAILABLE_EXCEPTION`	Alexa couldn't accept the message. Resend the message up to three times, with at least a one-second interval between each attempt. If the problem persists, contact Amazon Support.

Example 401 Unauthorized response body

The following example shows an error response.

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "The access token is invalid, expired, or malformed."
  }
}

Was this page helpful?

Provide feedback

Last updated: Aug 23, 2024