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 the assetId of the incoming directive, DO NOT play the asset.
If the assetId of the current directive does not match the assetId 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.

Was this page helpful?

Provide feedback