Alexa.ChangeReport Interface 3
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.
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.
{
"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.
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.
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 |
|---|---|---|---|
|
|
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 |
|
Yes |
|
|
Report the state of all other reportable properties. List these properties and their values in the |
|
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.
payload or the context, but not both.| Property | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the details of the change. |
Object |
Yes |
|
|
Reason for the change in one or more properties. |
|
Yes |
|
|
List of properties that changed. Include one object for each property that changed. |
Array of |
Yes |
Cause object
The following table shows the Cause object properties.
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Identifies what caused the change. |
|
Yes |
Type values
Use one of the following type values to describe the reason that the property value changed.
| Cause type | Description |
|---|---|
|
|
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 of an endpoint. For example, you might poll a temperature sensor every hour and send the updated temperature to Alexa. |
|
|
Physical interaction with an endpoint. For example, the user turned on a light or locked a door lock manually. |
|
|
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 |
|---|---|---|
|
|
— |
Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing. |
|
|
|
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. |
|
|
|
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. |
|
|
|
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. |
|
|
|
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. |
|
|
|
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. |
|
|
|
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. |
|
|
|
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. |
|
|
|
Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt. |
|
|
|
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. |
|
|
|
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."
}
}
Related topics
- Alexa.Discovery Interface
- Alexa.EndpointHealth Interface
- Alexa.Report State and Alexa.StateReport Interfaces
- Alexa Interface Message and Property Reference
- Operational Metrics
Last updated: Aug 23, 2024