Alexa.ProactiveNotificationSource Interface 3.0

Implement the Alexa.ProactiveNotificationSource interface in your Alexa skill so that Alexa can notify a customer when their device needs attention. For example, Alexa can notify the customer when their washing machine cycle completes, or when their oven reaches the target preheat temperature.

Alexa delivers the notification in the form of an announcement. First, the customer must opt-in to announcement notifications in the Alexa app. Then, based on the configured notification triggers, Alexa immediately broadcasts the resulting announcements on the customer's Amazon Echo devices. Customers can opt-out of announcements for each device.

You implement the Alexa.ProactiveNotificationSource interface with other interfaces that provide functionality for your device. You can use Alexa.ProactiveNotificationSource with one of the following interfaces:

For the list of languages that the Alexa.ProactiveNotificationSource interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

About proactive notifications

You configure proactive notifications for your device in your discovery response. Here, you define the conditions that trigger announcements to the customer. As soon as your skill sends an Alexa.ChangeReport that indicates a device needs attention, Alexa delivers the announcement on the customer's Echo devices. Announcements are supported on Echo devices, such as an Echo Dot, Echo Plus, Echo Show, or Echo Spot.

Announcements for cooking

You can use the Alexa.Cooking interface to notify the customer about the status of their food or when your appliance requires attention. To enable announcements, you include the cooking statuses that your device supports in the discovery response. For an example discovery response, see the Enable announcements for cooking appliances.

Later, you send a Alexa.ChangeReport event to Alexa to report a change to the status. When the Alexa.ChangeReport contains a CookingStatus value that has a resulting announcement, Alexa plays the announcement on the customer's Echo devices immediately. For example: "Your food in the oven is ready." For details about cooking statuses that trigger announcements, see CookingStatus.

Announcements for device state

You can use the Alexa.ModeController and Alexa.RangeController interfaces to notify the customer when your device requires attention. To enable announcements, you map each device property to a stateMappings value, such as Alexa.States.Done, Alexa.States.Full or Alexa.States.Stuck, and include a semantics object in your discovery response. For an example discovery response, see Enable device state announcements with semantics.

Later, you send a Alexa.ChangeReport event to Alexa to report a change to your device. When the Alexa.ChangeReport contains a property value mapped to one of the Alexa.States values, Alexa plays the announcement on the customer's Echo devices immediately.

Announcements by interface

You can use Alexa.ModeController and Alexa.RangeController to send announcements for the following device states.

State mapping value Interface Announcement

Alexa.States.Done

Alexa.ModeController

"Your <device friendly name> is done."

Alexa.States.Stuck

Alexa.ModeController

"Your <device friendly name> is stuck."

Alexa.States.Full

Alexa.RangeController

"Your <instance friendly name> is full."
"Your <device friendly name>'s <instance friendly name> is full."

State mapping value Interface Announcement

Alexa.States.Done

Alexa.ModeController

"Votre <device friendly name> est terminée."

Alexa.States.Stuck

Alexa.ModeController

"Votre <device friendly name> est bloqué."

Alexa.States.Full

Alexa.RangeController

"<instance friendly name> est plein."

State mapping value Interface Announcement

Alexa.States.Done

Alexa.ModeController

"<device friendly name> ist fertig."

Alexa.States.Stuck

Alexa.ModeController

"<device friendly name> ist stecken geblieben."

Alexa.States.Full

Alexa.RangeController

"<instance friendly name> ist voll."
"<instance friendly name> von <device friendly name> ist voll."

State mapping value Interface Announcement

Alexa.States.Done

Alexa.ModeController

"Il dispositivo <device friendly name> ha finito."

Alexa.States.Stuck

Alexa.ModeController

"Il dispositivo <device friendly name> ha smesso di muoversi."

Alexa.States.Full

Alexa.RangeController

"Il dispositivo <instance friendly name> è pieno."
"Il dispositivo <instance friendly name> del dispositivo <device friendly name> è pieno."

State mapping value Interface Announcement

Alexa.States.Done

Alexa.ModeController

"Tu <device friendly name> ha listo."

Alexa.States.Stuck

Alexa.ModeController

"Tu <device friendly name> ha dejado de moverse."

Alexa.States.Full

Alexa.RangeController

"Tu <instance friendly name> de <device friendly name> est lleno."

Announcement examples

The following examples show some announcements for state of a vacuum:

Your Robot vacuum is stuck.
Your bin is full.
Your Robot vacuum's bin is empty.
Your washer is done.

Votre État est bloqué.
Votre aspirateur est plein.
Votre aspirateur est vide.
Votre laveuse est terminée.

Dein staubsauger ist stecken geblieben.
Auffangbehälter ist voll.
Auffangbehälter von dein staubsauger ist leer.
Ihre Wäsche ist fertig.

Il dispositivo di aspirazione ha smesso di muoversi.
Il contenitore raccogli polvere di vuoto è pieno.
Il contenitore raccogli polvere di vuoto è vuoto.
Il dispositivo lavatrice ha finito.

Tu aspiradora ha dejado de moverse.
Tu depósito de vacio está lleno.
Tu depósito de vacio está vacío.
La ropa ha listo.

Reportable properties

The Alexa.ProactiveNotificationSource interface doesn't define any reportable properties

Discovery

You describe endpoints that support the Alexa.ProactiveNotificationSource interface by using the standard discovery mechanism described in Alexa.Discovery.

The Alexa.ProactiveNotificationSource interface doesn't have any reportable properties. Set retrievable and proactivelyReported to true as appropriate for other interfaces that you implement in your skill.

To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Configuration object

In addition to the usual discovery response fields, for Alexa.ProactiveNotificationSource, include a configuration object that contains an array of notificationConditions that trigger the notification.

NotificationConditions object

To define the conditions that trigger announcements, include the notificationConditions array. For generic controllers, include an NotificationConditions object for each controller instance that supports notifications. For the Cooking interface, you must include one NotificationConditions object only.

Field Description Type Required
conditionType The type of condition that triggers the notification.
Valid value: PropertyValueChange		 String Yes
property The property to evaluate the condition against. A Property object Yes
valueChangeCondition The condition that triggers the notification. If the condition evaluates to true, Alexa sends an announcement. A ValueChangeCondition object Yes

Property object

The Property object defines the specific property of an interface that triggers notifications.

Property Description Type Required

type

The type of interface.
Valid value: AlexaInterface

string

Yes

interface

Name of the Alexa interface that enables announcements.
Valid values: Alexa.Cooking, Alexa.ModeController, Alexa.RangeController

String

Yes

instance

(Optional) For generic controller interfaces, the instance of the interface. For example, Dryer.Temperature.
The Alexa.Cooking interface doesn't support instances.

String

No

name

Name of the property that triggers notifications.

String

Yes

ValueChangeCondition object

The ValueChangeCondition object defines the condition to evaluate against the property value. If the condition evaluates to true, Alexa sends an announcement. For device state notifications, Alexa sends the announcement only when the current state is different from the previous state.

To evaluate the property value against multiple cooking statuses, use StringIn. To evaluate the property value against multiple states, use StateIn.

Property Description Type Required

comparator

The comparison operator.
Valid comparators for cooking: StringEquals, StringIn Valid comparators for device state: StateEquals, StateIn

string

Yes

value

The values to which to compare the property value against.
For StringEquals and StateEquals comparators, include a single value.
For StringIn and StateIn comparators, include a list of values.

String or List of Strings

Yes

Enable announcements for cooking appliances example

The following example shows a Discover.Response message for an oven that uses the Alexa.Cooking interfaces. The example includes the Alexa.ProactiveNotificationSource interface to enable announcements when cooking completes.

Enable announcements with semantics example

The following example shows a Discover.Response message for a clothes dryer that uses the Alexa.ProactiveNotificationSource interface and semantics for announcements. The example uses three instances of the ModeController interface: one for the dryer temperature, one for the dryer cycle, and one for the lint filter. The example shows notification triggers enabled for two of the controllers by using the Alexa.ProactiveNotificationSource interface: to notify customers when the dryer cycle completes, and to notify customers when the lint filter is full.

Change reporting

You send an Alexa.ChangeReport event to report proactively on changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

Report dryer cycle completed example

The following Alexa.ChangeReport results in the following announcement: Alexa: Your dryer is done.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.ModeController",
            "instance": "Dryer.CurrentDryerCycle",
            "name": "mode",
            "value": "CurrentDryerCycle.Completed",
            "timeOfSample": "2024-05-01T09:30:05.05Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-05-01T09:30:00.05Z",
    "uncertaintyInMilliseconds": 0
  }
}

Report full vacuum bin example

The following Alexa.ChangeReport results in the following announcement: Alexa: Your vacuum bin is full.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.RangeController",
            "instance": "Vacuum.Bin",
            "name": "rangeValue",
            "value": "95",
            "timeOfSample": "2024-05-01T09:32:05.05Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-05-01T09:30:00.05Z",
    "uncertaintyInMilliseconds": 0
  }
}

Report cooking status example

The following Alexa.ChangeReport results in the following announcement: Alexa: Your food in the oven is ready.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.Cooking",
            "name": "cookingStatus",
            "value": "COOKING_COMPLETED",
            "timeOfSample": "2024-05-01T17:32:05.05Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2024-05-01T17:31:00.05Z",
    "uncertaintyInMilliseconds": 0
  }
}
Was this page helpful?

Last updated: Aug 23, 2024