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 with SetDoNotDisturb 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 a ReportDoNotDisturb event with the current device DND state. If cloud DND setting does not match the device setting, AVS will reply with a SetDoNotDisturb 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 a ReportDoNotDisturb event with the current device DND state. If cloud DND setting does not match the device setting, AVS will reply with a SetDoNotDisturb 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