Alexa.ProactiveNotificationSource Interface 3.0

Implement the Alexa.ProactiveNotificationSource interface in your Alexa add-on 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 add-on 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: 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.

English (All)
French (All)
German (DE)
Italian (IT)
Spanish (All)

State mapping value	Interface	Announcement
`Alexa.States.Done`	`Alexa.ModeController`
`Alexa.States.Stuck`	`Alexa.ModeController`
`Alexa.States.Full`	`Alexa.RangeController`

State mapping value	Interface	Announcement
`Alexa.States.Done`	`Alexa.ModeController`
`Alexa.States.Stuck`	`Alexa.ModeController`
`Alexa.States.Full`	`Alexa.RangeController`

State mapping value	Interface	Announcement
`Alexa.States.Done`	`Alexa.ModeController`
`Alexa.States.Stuck`	`Alexa.ModeController`
`Alexa.States.Full`	`Alexa.RangeController`

State mapping value	Interface	Announcement
`Alexa.States.Done`	`Alexa.ModeController`
`Alexa.States.Stuck`	`Alexa.ModeController`
`Alexa.States.Full`	`Alexa.RangeController`

State mapping value	Interface	Announcement
`Alexa.States.Done`	`Alexa.ModeController`
`Alexa.States.Stuck`	`Alexa.ModeController`
`Alexa.States.Full`	`Alexa.RangeController`

Announcement examples

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

English (All)
French (All)
German
Italian
Spanish

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 add-on. 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.

Show/hide discovery response

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "the manufacturer name",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Oven",
          "displayCategories": ["OVEN"],
          "additionalAttributes": {
            "manufacturer": "manufacturer name",
            "model": "sample model",
            "serialNumber": "the serial number of the oven",
            "customIdentifier": "your custom identifier for the oven"
          },
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.Cooking",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "cookingMode"
                  },
                  {
                    "name": "foodItem"
                  },
                  {
                    "name": "cookingTimeInterval"
                  },
                  {
                    "name": "cookingStatus"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportsRemoteStart": false,
                "supportedCookingModes": [
                  "OFF",
                  "PREHEAT",
                  "COOK"
                ],
                "supportedCookingStatuses": [
                  "COOKING",
                  "COOKING_COMPLETED",
                  "NOT_IN_USE"
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.Cooking.TimeController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "requestedCookTime"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportsRemoteStart": false,
                "supportedCookingModes": [
                  "PREHEAT",
                  "COOK"
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.Cooking.PresetController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "presetName"
                  },
                  {
                    "name": "requestedFoodDoneness"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "presetCatalogId": "catalog ID",
                "supportsRemoteStart": false,
                "supportedCookingModes": [
                  "PRESET",
                  "PREHEAT",
                  "COOK"
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ProactiveNotificationSource",
              "version": "3.0",
              "proactivelyReported": true,
              "configuration": {
                "notificationConditions": [
                  {
                    "conditionType": "PropertyValueChange",
                    "property": {
                      "type": "AlexaInterface",
                      "interface": "Alexa.Cooking",
                      "name": "cookingStatus"
                    },
                    "valueChangeCondition": {
                      "comparator": "StringEquals",
                      "value": "COOKING_COMPLETED"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

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.

Show/hide discovery response

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Clothes Dryer Maker",
                "description": "Smart Clothes Dryer by Dryer Maker",
                "friendlyName": "Dryer",
                "displayCategories": [
                    "DRYER"
                ],
                "additionalAttributes": {
                    "manufacturer" : "Clothes Dryer Maker",
                    "model" : "Sample Model",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Dryer.Temperature",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": false
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "Temperature",
                                    "locale": "en-US"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": true,
                            "supportedModes": [{
                                    "value": "Dryer.Temperature.Cool",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Cool",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.Temperature.Warm",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Warm",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.Temperature.Hot",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Hot",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Dryer.CurrentDryerCycle",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": true
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "Current dryer cycle",
                                    "locale": "en-US"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": true,
                            "supportedModes": [{
                                    "value": "CurrentDryerCycle.NotStarted",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "NotStarted",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentDryerCycle.Drying",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Drying",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentDryerCycle.CoolDown",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "CoolDown",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "CurrentDryerCycle.Completed",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Completed",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                }
                            ]
                        },
                        "semantics": {
                            "stateMappings": [{
                                "@type": "StatesToValue",
                                "states": [
                                    "Alexa.States.Done"
                                ],
                                "value": "CurrentDryerCycle.Completed"
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ModeController",
                        "instance": "Dryer.LintTrap",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "mode"
                            }],
                            "retrievable": true,
                            "proactivelyReported": true,
                            "nonControllable": true
                        },
                        "capabilityResources": {
                            "friendlyNames": [{
                                "@type": "text",
                                "value": {
                                    "text": "Lint trap",
                                    "locale": "en-US"
                                }
                            }]
                        },
                        "configuration": {
                            "ordered": false,
                            "supportedModes": [{
                                    "value": "Dryer.LintTrap.Clean",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Clean",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.LintTrap.Medium",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Medium",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                },
                                {
                                    "value": "Dryer.LintTrap.Full",
                                    "modeResources": {
                                        "friendlyNames": [{
                                            "@type": "text",
                                            "value": {
                                                "text": "Full",
                                                "locale": "en-US"
                                            }
                                        }]
                                    }
                                }
                            ]
                        },
                        "semantics": {
                            "stateMappings": [{
                                "@type": "StatesToValue",
                                "states": [
                                    "Alexa.States.Full"
                                ],
                                "value": "Dryer.LintTrap.Full"
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ProactiveNotificationSource",
                        "version": "3.0",
                        "proactivelyReported": true,
                        "configuration": {
                            "notificationConditions": [{
                                    "conditionType": "PropertyValueChange",
                                    "property": {
                                        "type": "AlexaInterface",
                                        "interface": "Alexa.ModeController",
                                        "instance": "Dryer.CurrentDryerCycle",
                                        "name": "mode"
                                    },
                                    "valueChangeCondition": {
                                        "comparator": "StateEquals",
                                        "value": "Alexa.States.Done"
                                    }
                                },
                                {
                                    "conditionType": "PropertyValueChange",
                                    "property": {
                                        "type": "AlexaInterface",
                                        "interface": "Alexa.ModeController",
                                        "instance": "Dryer.LintTrap",
                                        "name": "mode"
                                    },
                                    "valueChangeCondition": {
                                        "comparator": "StateEquals",
                                        "value": "Alexa.States.Full"
                                    }
                                }
                            ]
                        }
                    },
                     {
                       "type": "AlexaInterface",
                       "interface": "Alexa.EndpointHealth",
                       "version": "3",
                       "properties": {
                       "supported": [
                                 {
                                 "name": "connectivity"
                                 }
                                   ],
                       "proactivelyReported": true,
                       "retrievable": true
                       }
                     },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

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:

{  
  "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:

{
  "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:

{
  "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
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.ProactiveNotificationSource Interface 3.0

About proactive notifications

Announcements for cooking

Announcements for device state

Announcements by interface

Announcement examples

Reportable properties

Discovery

Configuration object

NotificationConditions object

Property object

ValueChangeCondition object

Enable announcements for cooking appliances example

Enable announcements with semantics example

Change reporting

Report dryer cycle completed example

Report full vacuum bin example

Report cooking status example

​About proactive notifications

​Announcements for cooking

​Announcements for device state

​Announcements by interface

​Announcement examples

​Reportable properties

​Discovery

​Configuration object

​NotificationConditions object

​Property object

​ValueChangeCondition object

​Enable announcements for cooking appliances example

​Enable announcements with semantics example

​Change reporting

​Report dryer cycle completed example

​Report full vacuum bin example

​Report cooking status example

​Related topics

About proactive notifications

Announcements for cooking

Announcements for device state

Announcements by interface

Announcement examples

Reportable properties

Discovery

Configuration object

NotificationConditions object

Property object

ValueChangeCondition object

Enable announcements for cooking appliances example

Enable announcements with semantics example

Change reporting

Report dryer cycle completed example

Report full vacuum bin example

Report cooking status example

Related topics