Alexa.DoNotDisturb 1.0
The Alexa.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.
Capability assertion
Alexa.DoNotDisturb 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the 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
ReportDoNotDisturb
event, and if the device state differs from the server, then the server DND state will be propagated to device withSetDoNotDisturb
directive. - If the DND setting has changed in the device, the device sends a
DoNotDisturbChanged
event, 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
SetDoNotDisturb
directive, the device should send aReportDoNotDisturb
event with the current device DND state. If cloud DND setting does not match the device setting, AVS will reply with aSetDoNotDisturb
directive containing the cloud's DND state. - When the cloud fails to update the DND setting after the device sends a
DoNotDisturbChanged
event, AVS will send a 400 or 500 HTTP error. The device should respond with aReportDoNotDisturb
event with the current device DND state. If cloud DND setting does not match the device setting, AVS will reply with aSetDoNotDisturb
directive containing the cloud's DND state.
Directives
SetDoNotDisturb
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.
Sample Message
{ "directive": { "header": { "namespace": "Alexa.DoNotDisturb", "name": "SetDoNotDisturb", "messageId": "{{STRING}}" }, "payload": { "enabled": {{BOOLEAN}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID that identifies a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
enabled | true to enable doNotDisturb ; false to disable doNotDisturb . |
boolean |
Events
ReportDoNotDisturb
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.
Sample Message
{ "event": { "header": { "namespace": "Alexa.DoNotDisturb", "name": "ReportDoNotDisturb", "messageId": "{{STRING}}" }, "payload": { "enabled": {{BOOLEAN}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID that identifies a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
enabled | true to enable doNotDisturb ; false to disable doNotDisturb . |
boolean |
Responses
AVS sends the error responses in the Exception Message format.
Code | HTTP status code | Description |
---|---|---|
INVALID_REQUEST_EXCEPTION | 400 | The request was malformed. |
INTERNAL_REQUEST_EXCEPTION | 500 | Internal service exception. |
N/A | 200 or 204 | On successful processing of the request, HTTP 200 or 204 will be sent back to the client. |
DoNotDisturbChanged
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.
Sample Message
{ "event": { "header": { "namespace": "Alexa.DoNotDisturb", "name": "DoNotDisturbChanged", "messageId": "{{STRING}}" }, "payload": { "enabled": {{BOOLEAN}} } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID that identifies a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
enabled | true or false represents the current doNotDisturb setting on the device. |
boolean |
Responses
Code | HTTP status code | Description |
---|---|---|
INVALID_REQUEST_EXCEPTION | 400 | The request was malformed. |
INTERNAL_SERVICE_EXCEPTION | 500 | Internal service exception. |
N/A | 200 or 204 | On successful processing of the request, HTTP 200 or 204 will be sent back to the client. |
Last updated: May 10, 2021