Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

How To Use the State Reporting Test Tool

The state reporting test tool enables you to see when your skill is being queried for the current state of endpoint properties, or when Alexa relies on proactive ChangeReport events to report endpoint properties. You can use this information to debug your smart home skill.


To use the troubleshooting and testing tips in this document, you must:

  • Implement a smart home skill that sends state updates (ChangeReport) events to the Alexa event gateway.

  • Send ChangeReport events when the properties of an endpoint change. This means your discovery response indicates proactivelyReported=true for all properties defined in capabilities supported by the endpoint. If your implementation only supports proactive reporting for a subset of an endpoint's properties you will be unable to use this tool and guide.

For more information see the following topics:

1. Get access to the tool

To request access to the state reporting test tool, complete the following steps:

You will be contacted when you are granted access or if we need more information.

2. Sign in and enable your skill

The tool is an add-on to the existing web-based Alexa app. Make sure to use the Alexa app for your region and sign in with the same developer account that you used to request access to the testing tool.

Following is a list of regions and the URL for the Alexa app:

If you haven’t already done so, enable and account-link your smart home skill. For more information on how to do this, see Steps to Build a Smart Home Skill.

3. View and understand the state information

In the Alexa app, navigate to Smart Home and then Devices. If the tool has been successfully enabled for your developer account, you should see extended debugging information for each device. The following image shows an example device:

Each Capability states line in the tool output represents an endpoint property that you marked as proactively reported in your discovery response, the current settings for the property, and whether a query was made for that property.

For example, the Wireless In_wall Dimmer endpoint shown in the image has the following property values:

  • connectivity: OK
  • brightness: 0
  • powerState: OFF

The following image shows a more detailed view of the property reporting.

Pay special attention to the DeepQuery value. This is a boolean that indicates if your proactive state update events and other event data is being used, or if a query occurred to provide the property value.

  • DeepQuery=True: Indicates Alexa either did not have the value cached or updated the cached value before reporting it by sending a ReportState directive to the skill. The value reported was provided in the StateReport event sent by the skill in response.

  • DeepQuery= False: Indicates that Alexa provided the cached value of the property.

4. Troubleshoot

If you believe you have properly implemented proactive state updates, but the tool shows DeepQuery=True, check the following:

  • If you are working with a newly discovered endpoint, the state cache might be empty. Try refreshing the Alexa app in your browser.
  • Ensure you have indicated proactivelyReported=true for all properties defined in the endpoint's capabilities, and that you are reporting all property values. This includes the connectivity property defined by EndpointHealth.
  • Conversely, ensure that you are only reporting the values of properties defined in your endpoint's capabilities. For example, if your endpoint implements the BrightnessController interface, you would not report brightnessDelta as proactivelyReported since this is not a capability property.
  • For thermostat devices, you may need to toggle between HEAT/COOL and AUTO modes to ensure we have cached data for all supported set points reported during device discovery.

5. Perform additional tests

After you have confirmed that DeepQuery=False for all of your properties, you should exercise all of the scenarios that can trigger proactive state updates and confirm that property values update in the debugging tool.

  • Manipulate your device state without using Alexa. For example, use another application or the physical device controls to turn a device on or off or change its settings. This should cause your skill to send one or more proactive state updates to the Alexa event gateway. In your browser, refresh the Alexa app to confirm that DeepQuery=False and that the properties show the expected state of the device.
  • Make sure to test EndpointHealth proactive state updates. To do this, remove the power or power source from your device and wait for the specified device health polling interval. Refresh your browser and check the Alexa app for the device state. Inversely, restore power to the device and ensure that all properties are correctly updated in the Alexa app.
  • Validate that you are sending proactive state updates for all Amazon accounts that have enabled and account-linked the skill; not just the first or more recent accounts to be linked. Commonly, customers in the same household share smart home devices but have their own Amazon accounts associated with the skills for those devices. To test this scenario, enable and account-link the skill from different Amazon accounts using the same device credentials. Then, change the state of the device without using Alexa. Use the debugging tool, logging in as each Amazon user, and confirm the property states are accurate, but that DeepQuery is false. This helps confirm that you are correctly sending ChangeReport events for each user. Note that this test will require that you have enabled at least two Amazon accounts to use the troubleshooting tool. Refer to Section 1 if you need to enable additional accounts. Make sure to login from the account you want to enable before you complete the Contact Us form.
  • Inspect your log responses to ensure your proactive state updates are being sent correctly to the Alexa event gateway.

Finally if you encounter problems using this debugging approach, please use the Developer Support contact form.