Alexa.ChangeReport Interface 3

Implement the Alexa.ChangeReport event in your Alexa add-on 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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Discovery

During discovery, you identify the interfaces that your add-on supports and the reportable properties of each interface. When you set proactivelyReported = true for an interface, your add-on 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 add-on that controls a light and supports the Alexa.PowerController, Alexa.BrightnessController, and Alexa.EndpointHealth interfaces. The powerState, brightness, and connectivity properties are reportable.

{
    "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.

ChangeReport event example

The following example shows an Alexa.ChangeReport event that your add-on sends to Alexa proactively. The endpointId identifies the device and the scope identifies the customer. In the example, the add-on 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.

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 add-on 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.

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 add-on might receive from the Alexa event gateway. If you receive an error, the response body contains the error code and description. 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 not valid 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 expired, malformed, or not valid. Refresh your token and retry the request. If a user disables your add-on, that also invalidates the access token.
`403 Forbidden`	`SKILL_DISABLED_EXCEPTION`	The customer disabled your add-on. Stop sending events for the customer and delete any stored tokens in your system.
`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. Otherwise, the customer never enabled your add-on.
`403 Forbidden`	`INSUFFICIENT_PERMISSION_EXCEPTION`	Token doesn’t have the required permissions. Make sure that the add-on 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 directed identifier that’s not valid. 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 add-on was in different stage, such as certification. Try disabling and re-enabling the add-on 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 error response body

The following example shows an error response.

HTTP/1.1 401 Unauthorized
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "Unique version 4 UUID"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "The access token is invalid, expired, or malformed."
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Discovery

Discover response example

Change reporting

ChangeReport event example

ChangeReport event properties

Payload object

Cause object

Type values

ChangeReport response

Response body parameters

HTTP status codes

Example error response body

​Discovery

​Discover response example

​Change reporting

​ChangeReport event example

​ChangeReport event properties

​Payload object

​Cause object

​Type values

​ChangeReport response

​Response body parameters

​HTTP status codes

Example error response body

​Related topics

Discovery

Discover response example

Change reporting

ChangeReport event example

ChangeReport event properties

Payload object

Cause object

Type values

ChangeReport response

Response body parameters

HTTP status codes

Related topics