Alexa.ChangeReport Interface

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.

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": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the endpoint of the light ",
                "manufacturerName": "the manufacturer name of the endpoint",
                "description": "a description that is shown in the Alexa app",
                "friendlyName": "Living Room Light",
                "displayCategories": ["LIGHT"],
                "additionalAttributes": {
                    "manufacturer": "the manufacturer name of the endpoint",
                    "model": "the model of the device",
                    "serialNumber": "the serial number of the device",
                    "firmwareVersion": "the firmware version of the device",
                    "softwareVersion": "the software version of the device",
                    "customIdentifier": "your 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"
                    }
                ]
            }]
        }
    }
}

ChangeReport event

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.

.

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": "a 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-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.BrightnessController",
                "name": "brightness",
                "value": 75,
                "timeOfSample": "2022-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2022-02-03T16:20:50.52Z",
                "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.

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 event was accepted 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."
  }
}