DoNotDisturb Interface
- Capabilities API
- Authoritativeness of the cloud DND setting
- SetDoNotDisturb Directive
- ReportDoNotDisturb Event
- DoNotDisturbChanged Event
The
DoNotDisturb (DND) interface allows users to block all incoming notifications, announcements, and calls to their devices. Users can set daily recurring schedules that turn DND off and on.
DND can be set via:
- The Amazon Alexa app.
- Voice utterance. For example, "Turn on Do Not Disturb," "Don't disturb me," "Turn off Do Not Disturb."
- DND schedule. Daily recurring DND schedules can be created using the Alexa app.
- The device interface.
Capabilities API
To use version 1.0 of the
DoNotDisturb interface, it must be declared in your call to the Capabilities API. For additional details, see Capabilities API.
Sample Object
{ "type": "AlexaInterface", "interface": "Alexa.DoNotDisturb", "version": "1.0" }
Authoritativeness of the cloud DND setting
For DND, the cloud server setting is authoritative. When device and cloud become out of sync, the cloud state will be propagated to the device. Some specific scenarios of resolving conflicts between cloud and device follow.
After the device has been offline and come back online:
- If the DND setting has not changed in the device, the device must send a
ReportDoNotDisturbevent, and if the device state differs from the server, then the server DND state will be propagated to device with
SetDoNotDisturbdirective.
- If the DND setting has changed in the device, the device sends a
DoNotDisturbChangedevent, and the server's DND state is overwritten by the device state.
After update failures on the server or the device:
- When the device fails to update a after receiving a
SetDoNotDisturbdirective, the device should send a
ReportDoNotDisturbevent with the current device DND state. If cloud DND setting does not match the device setting, AVS will reply with a
SetDoNotDisturbdirective containing the cloud's DND state.
- When the cloud fails to update the DND setting after the device sends a
DoNotDisturbChangedevent, AVS will send a 400 or 500 HTTP error. The device should respond with a
ReportDoNotDisturbevent with the current device DND state. If cloud DND setting does not match the device setting, AVS will reply with a
SetDoNotDisturbdirective containing the cloud's DND state.
SetDoNotDisturb Directive
This directive instructs your device to enable or disable DND.
Your client should respond by updating the local DND state to the value in the payload and sending a
ReportDoNotDisturb event after its success or failure in processing the directive, including the current DND state on the device. When the device receives a
SetDoNotDisturb directive, it must not handle any other directives on the
DoNotDisturb interface until it has replied with a
ReportDoNotDisturb event.
If the device is offline and a scheduled update changes the DND state in the cloud, the directive delivery to the client will fail. When the device comes back online, the device sends a
ReportDoNotDisturb event. If the payload in the event is different from the server's current DND setting, AVS sends a new
SetDoNotDisturb directive to update the device.
Required: [header, payload]
Sample Message
{ "directive": { "header": { "namespace": "Alexa.DoNotDisturb", "name": "SetDoNotDisturb", "messageId": "{{STRING}}" }, "payload": { "enabled": {{BOOLEAN}} } } }
Header Parameters
Payload Parameters
ReportDoNotDisturb Event
This event must be sent when the device updates the
DoNotDisturb setting in response to a
SetDoNotDisturb directive, or when a
DoNotDisturbChanged event fails.
When AVS receives a
ReportDoNotDisturb event, AVS compares the device DND setting sent in the payload and the cloud DND setting. If the
ReportDoNotDisturb values differ, AVS sends a
SetDoNotDisturb directive to the device with the cloud DND setting value.
Required: [header, payload]
Sample Message
{ "event": { "header": { "namespace": "Alexa.DoNotDisturb", "name": "ReportDoNotDisturb", "messageId": "{{STRING}}" }, "payload": { "enabled": {{BOOLEAN}} } } }
Header Parameters
Payload Parameters
Responses
AVS will send the error responses in the Exception Message format.
DoNotDisturbChanged Event
Event sent to AVS after the
DoNotDisturb state is modified on the device.
The client must send the
DoNotDisturbChanged event to AVS when
DoNotDisturb is enabled or disabled locally on the device. When the client receives a "200 OK" or a 204 response, it should update the
DoNotDisturb state to reflect the setting change. If the client receives an error response, it should not change the
DoNotDisturb state. The device must not handle any other directives on the
DoNotDisturb interface until an event response is received.
If the user toggles the setting when the device is offline, the selected DND state should be applied on the device immediately. When the device comes back online it must send a
DoNotDisturbChanged event with the most recent DND value. If an error response is returned, the device must then send a
ReportDoNotDisturb event, which propagates the cloud DND state to the device. If the user changes the DND setting multiple times when the device is offline, when the device comes back online it must propagate only the latest DND setting.
Required: [header, payload]
Sample Message
{ "event": { "header": { "namespace": "Alexa.DoNotDisturb", "name": "DoNotDisturbChanged", "messageId": "{{STRING}}" }, "payload": { "enabled": {{BOOLEAN}} } } }
Header Parameters
Payload Parameters