Notifications 1.0
The Notifications interface allows AVS to inform users that new content is available from Alexa domains or an enabled Alexa skill. Specifically, the interface exposes two directives that instruct your client to render and clear visual and audio indicators for the user.
This interface does not provide the content for a notification, it only provides the audio and visual indicators that are used to inform the user that new content is available. For example, the product may flash a yellow LED and play an audio file, at which time a user can retrieve any pending notifications by asking, "Alexa, what did I miss?" or "Alexa, what are my notifications?"
For information about flow and delivery, the do not disturb setting, and UX considerations, see the Notifications Overview.
Capability assertion
Notifications 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": "Notifications", "version": "1.0" }
Context
Alexa expects a client to report the state of a product's notification indicator with each event that requires context.
To learn more about reporting Context, see Context Overview.
Sample Message
{ "header": { "namespace": "Notifications", "name": "IndicatorState" }, "payload": { "isEnabled": {{BOOLEAN}}, "isVisualIndicatorPersisted": {{BOOLEAN}} } }
Payload Parameters
Parameter | Description | Type |
---|---|---|
isEnabled | Indicates there are new or pending notifications that have not been communicated to the user. Note: Any indicator that has not been cleared is considered enabled. |
boolean |
isVisualIndicatorPersisted | Corresponds to the persistVisualIndicator value of the last SetIndicator directive received. If persistVisualIndicator was true for the last directive received, upon reconnecting, isVisualIndicatorPersisted must be true . |
boolean |
Directives
SetIndicator
This directive instructs your client to render visual and audio indicators when a notification is available to be retrieved. Your client may receive multiple SetIndicator
directives in a short period of time. If directives overlap, consider these rules:
- If the
assetId
of the current directive matches theassetId
of the incoming directive, DO NOT play the asset. - If the
assetId
of the current directive does not match theassetId
of the incoming directive, play the asset for the incoming directive AFTER playback of the current asset is finished.
Sample Message
{ "directive": { "header": { "namespace": "Notifications", "name": "SetIndicator", "messageId": "{{STRING}}" }, "payload": { "persistVisualIndicator": {{BOOLEAN}}, "playAudioIndicator": {{BOOLEAN}}, "asset": { "assetId": "{{STRING}}", "url": "{{STRING}}" } } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
Parameter | Description | Type |
---|---|---|
persistVisualIndicator | Specifies if your product must display a persistent visual indicator (if applicable) after handling this directive. | boolean |
playAudioIndicator | Specifies if your product must play an audio indicator when this directive is handled. | boolean |
asset | Contains information about the audio asset that must be played if playAudioIndicator is true . |
object |
asset.assetId | A unique identifier for the asset. | string |
asset.url | This asset may be downloaded and cached by your client. The URL provided is valid for 60 minutes. If the product is offline, or if the asset isn’t available, your product should play the default indicator sound. | string |
ClearIndicator
This directive instructs your client to clear all active visual and audio indicators.
- If an audio indicator is playing when this directive is received, it should be stopped immediately.
- If any visual indicators are set when this directive is received, they should be cleared immediately.
Sample Message
{ "directive": { "header": { "namespace": "Notifications", "name": "ClearIndicator", "messageId": "{{STRING}}" }, "payload": { } } }
Header Parameters
Parameter | Description | Type |
---|---|---|
messageId | A unique ID used to represent a specific message. | string |
Payload Parameters
This directive has an empty payload.