Alexa.SecurityPanelController.Alert Interface 1.1


Implement the Alexa.SecurityPanelController.Alert interface in your Alexa skill so that customers can augment their security system endpoints with sound from Alexa-enabled devices. Your skill reports the security alerts, such as chirps and sirens, and Alexa plays the corresponding sound. Customers can choose to enable or disable each of the security alerts in the Alexa app.

If your security panel is a component of a larger security system, your skill can also implement the Alexa.ContactSensor, Alexa.MotionSensor, and Alexa.SecurityPanelController interfaces.

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

Supported alerts

The Alexa.SecurityPanelController.Alert interface supports the following alerts that mirror security system sounds:

  • Siren – Played when the security system sounds an alarm. Alexa can play the audio clip multiple times in a loop with an optional pause between iterations. The maximum play time is 10 minutes.
  • Entry delay alert – Reminder chirps to alert the customer to disarm the system before the siren sounds. The maximum play time should match the delay duration on the security system.
  • Exit delay alert – Reminder chirps to alert the customer to exit before the system arms. The maximum play time should match the delay duration on the security system.
  • Chime – Audible tone triggered by a sensor, such as a contact sensor. Most often this sound plays when a window or door opens. Alexa plays this tone if there are no other sounds playing. Chimes last about one second and expire after five seconds.

If your skill reports multiple alerts, Alexa plays the sounds in the following order of precedence: siren, entry delay, exit delay alert, chime.

Utterances

The Alexa.SecurityPanelController.Alert interface doesn't have any user utterances. However, if your skill supports the Alexa.SecurityPanelController and the Alexa.SecurityPanelController.Alert interfaces, your skill sends an Alexa.SecurityPanelController.Alert event when the user arms or disarms the security system with the Alexa.SecurityPanelController pre-built voice interaction model.

The following examples show some customer utterances.

Alexa, arm my home.
Alexa starts playing the exit delay sound.
Alexa, disarm my home.
Alexa stops playing the siren or entry delay sound.

Alexa, arme ma maison.
Alexa stops playing the exit delay sound.
Alexa, désarme ma maison.
Alexa stops playing the siren or entry delay sound.

Alexa, stelle mein Haus scharf.
Alexa stops playing the exit delay sound.
Alexa, entschärfe mein Zuhause.
Alexa stops playing the siren or entry delay sound.

Alexa, arma la mia casa.
Alexa stops playing the exit delay sound.
Alexa, disarma la mia casa.
Alexa stops playing the siren or entry delay sound.

アレクサ、警備を開始して
Alexa stops playing the exit delay sound.
アレクサ、警備を解除して
Alexa stops playing the siren or entry delay sound.

Alexa, arma minha casa.
Alexa stops playing the exit delay sound.
Alexa, desarme minha casa.
Alexa stops playing the siren or entry delay sound.

Alexa, arma mi casa.
Alexa stops playing the exit delay sound.
Alexa, desarma mi casa.
Alexa stops playing the siren or entry delay sound.

Properties and objects

The Alexa.SecurityPanelController.Alert interface includes the following properties and objects.

Reportable properties

The Alexa.SecurityPanelController.Alert interface defines sirenState and entry and exit delayState as reportable properties. You identify that you support one or both of the properties in your discovery response.

Property Description Type Required

delayState

Defines the entry and exit delay and the associated playlist. If no sirens are playing, Alexa plays the entry and exit delay alerts.

Object

No

delayState.state

Indicates the current delay state of the endpoint. If the state is ENTRY_DELAY or EXIT_DELAY, Alexa plays the associated delay alert. If the state is NONE, Alexa cancels or stops the delay sound.
Valid values: ENTRY_DELAY, EXIT_DELAY, NONE.

String

Yes

delayState.delayInSeconds

Duration in seconds that the delay sound plays. Set the value to match the entry or exist duration on your security system. Include when delayState.state set to ENTRY_DELAY or EXIT_DELAY.
Amazon recommends that you set the delay to at least 30 seconds.
Valid values: 0 – 300.

Integer

No

delayState.playlistId

Unique identifier for the alert. Amazon recommends that you use a randomly generated version 4 UUID.
If you include delayState.playOrder, Alexa ignores this property. If you don't include delayState.playlistId or delayState.playOrder, Alexa plays the default playlist defined in the alerts object in your discovery response. Valid value: String of alphanumeric characters and dashes up to 128 characters.

String

No

delayState.playOrder

Ordered list of audio alerts.
If you don't include delayState.playlistId or delayState.playOrder, Alexa plays the default playlist defined in the alerts object in your discovery response.

Array of PlaylistItem objects

No

sirenState

Defines the siren state and the associated playlist. Siren alerts take precedence over delay alerts.

Object

No

sirenState.state

Indicates the current siren state of the endpoint. If the state is ON, Alexa plays the associated siren alert. If the state is OFF, Alexa cancels or stops the siren sound.
Valid values: ON, OFF.

String

Yes

sirenState.playlistId

Unique identifier for the alert. Amazon recommends that you use a randomly generated version 4 UUID.
If you include sirenState.playOrder, Alexa ignores this property. If you don't include sirenState.playlistId or sirenState.playOrder, Alexa plays the default playlist defined in the alerts object in your discovery response.
Valid value: String of alphanumeric characters and dashes up to 128 characters.

String

No

sirenState.playOrder

Ordered list of audio alerts.
If you don't include sirenState.playlistId or sirenState.playOrder, Alexa plays the default playlist defined in the alerts object in your discovery response.

Array of PlaylistItem objects

No

PlaylistItem object

Property Description Type Required

assetId

Identifies the audio to play. You define the audio assets in the Configuration object in your discovery response.

String

Yes

loopCount

Number of times to play the audio asset. Default is one time.

Integer

No

loopPauseInMilliseconds

When you specify a loop count greater than one, the loopPauseInMilliseconds defines the number of milliseconds to pause between each loop. For no pause, set to zero. Default is zero.

Integer

No

Discovery

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

Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

Use SECURITY_PANEL, MOTION_SENSOR, SMARTLOCK, or other appropriate display category. For the full list of display categories, see display categories.

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 the Alexa.SecurityPanelController.Alert entry in the capabilities array, include a configuration object that contains the following fields.

Property Description Type Required

assets

A list of audio to play to the user.

Array of objects

Yes

assets[].id

Unique identifier for the audio. Amazon recommends that you use a randomly generated version 4 UUID.
Valid value: String of alphanumeric characters and dashes up to 128 characters.

String

Yes

assets[].url

Location of the audio file. You must host the audio file at an Internet-accessible HTTPS endpoint on port 443. If the URL is broken, Alexa won't play any audio.

String

Yes

playlists

List of audio alerts to play.

Array of objects

Yes

playlists[].id

Unique identifier for the playlist. Amazon recommends that you use a randomly generated version 4 UUID.
Valid value: String of alphanumeric characters and dashes up to 128 characters.

String

No

playlists[].playOrder

Ordered list of audio alerts.

Array of PlaylistItem objects

No

alerts

List of audio alerts that your endpoint supports. The Alexa app displays these alerts to the customer and enables the customer to chose enable or disable each alert. Alexa plays these sounds on receipt of the Chime event.

Array of objects

Yes

alerts[].type

Identifies the alert type.
Valid values: CHIME, SIREN, ENTRY_DELAY, EXIT_DELAY.

  • CHIME – Audible tone triggered by a sensor, such as a contact sensor. Most often this sound plays when a window or door opens. Alexa plays this tone if there are no other sounds playing. Set the duration to about one second.
  • SIREN – Loud, piercing alarm sound triggered by intruders. Set the duration to no more than 10 minutes.
  • ENTRY_DELAY – Reminder chirps to alert the customer to disarm the endpoint before the alarm sounds. Set the duration to about one minute.
  • EXIT_DELAY – Reminder chirps to alert the customer to arm the endpoint before the alarm sounds. Set the duration to about one minute.

String

Yes

alerts[].defaultPlaylistId

Unique identifier for the playlist for Amazon Echo devices.

String

Yes

Discover response example

The following example shows an Alexa.Discover.Response message for a device that supports the Alexa.SecurityPanelController.Alert interface.

Copied to clipboard.

{
    "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": "Manufacturer name of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Your security panel name, displayed in the Alexa app",
                "displayCategories": ["SECURITY_PANEL"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer name of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.SecurityPanelController.Alert",
                        "version": "1.1",
                        "properties": {
                            "supported": [{
                                    "name": "delayState"
                                },
                                {
                                    "name": "sirenState"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "assets": [{
                                    "id": "UUID.1",
                                    "url": "https://example.com/url-of-the-stream-to-play.1.mp3"
                                },
                                {
                                    "id": "UUID.2",
                                    "url": "https://example.com/url-of-the-stream-to-play.2.mp3"
                                },
                                {
                                    "id": "UUID.3",
                                    "url": "https://example.com/url-of-the-stream-to-play.3.mp3"
                                }
                            ],
                            "playlists": [{
                                    "id": "UUID.entry.delay.1",
                                    "playOrder": [{
                                            "assetId": "UUID.1",
                                            "loopCount": 10,
                                            "loopPauseInMilliseconds": 1000
                                        },
                                        {
                                            "assetId": "UUID.2",
                                            "loopCount": 5,
                                            "loopPauseInMilliseconds": 500
                                        }
                                    ]
                                },
                                {
                                    "id": "UUID.playlist-chime.1",
                                    "playOrder": [{
                                        "assetId": "UUID.1"
                                    }]
                                },
                                {
                                    "id": "UUID.playlist-siren.1",
                                    "playOrder": [{
                                        "assetId": "UUID.3"
                                    }]
                                }
                            ],
                            "alerts": [{
                                    "type": "ENTRY_DELAY",
                                    "defaultPlaylistId": "UUID.entry.delay.1"
                                },
                                {
                                    "type": "EXIT_DELAY",
                                    "defaultPlaylistId": "UUID.entry.delay.1"
                                },
                                {
                                    "type": "SIREN",
                                    "defaultPlaylistId": "UUID.playlist-siren.1"
                                },
                                {
                                    "type": "CHIME",
                                    "defaultPlaylistId": "UUID.playlist-chime.1"
                                }
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.SecurityPanelController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "armState"
                                },
                                {
                                    "name": "burglaryAlarm"
                                },
                                {
                                    "name": "fireAlarm"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedArmStates": [{
                                    "value": "ARMED_AWAY"
                                },
                                {
                                    "value": "ARMED_STAY"
                                },
                                {
                                    "value": "DISARMED"
                                }
                            ],
                            "supportedAuthorizationTypes": [{
                                "type": "FOUR_DIGIT_PIN"
                            }]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }]
            }]
        }
    }
}

Directives and events

The Alexa.SecurityPanelController.Alert interface defines the following event.

Chime event

Send a Chime event to the Alexa event gateway to notify Alexa proactively of a security-related event, such as a chime, siren, or entry and exit delay. For details, see Send Events to the Event Gateway. Send the event as soon as the security-related event occurs. Alexa ignores events older than five seconds.

Chime event examples

The following examples show Chime events that a contact sensor skill sends to Alexa to play a chime alert.

Chime event payload

The following table shows the payload details for the Chime event.

Property Description Type Required

playlistId

Unique identifier for the playlist.. You define playlists in the Configuration object in your discovery response.
If you include playOrder, Alexa ignores this property. If you don't include playlistId or playOrder, Alexa plays the default playlist defined in the alerts object. Valid value: String of alphanumeric characters and dashes up to 128 characters.

String

No

playOrder

Ordered list of audio alerts.
If you don't include playlistId or playOrder, Alexa plays the default playlist defined in the alerts object in your discovery response.

Array of PlaylistItem objects

No

timestamp

Time the event occurred. Alexa ignores chime events with timestamps older than five seconds or specified in the future.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

Yes

HTTP status codes

The following table shows the HTTP status code values that your skill might receive from the Alexa event gateway. If you receive an error, the payload object contains a code and description field. Use these fields for logging only.

Status Payload code Description

202 Accepted

Request is authorized and the message is a syntactically valid event. The gateway accepted the event for further logical validation and processing.

400 Bad Request

INVALID_REQUEST_EXCEPTION

Message is invalid due to missing fields, incorrect values, or malformed JSON. Check your messages against the documentation to verify that your message contains all the required fields.

401 Unauthorized

INVALID_ACCESS_TOKEN_EXCEPTION

Message didn't include the authorization token or the token is invalid, expired, or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. Here, the user revoked authorization, and you can stop sending change reports for them.

403 Forbidden

SKILL_NEVER_ENABLED_EXCEPTION

You're not allowed access to the event gateway. Make sure that you're sending the events to the correct regional endpoint. For example, send events in North America to the North American endpoint.

403 Forbidden

INSUFFICIENT_PERMISSION_EXCEPTION

Token doesn't have the required permissions. Make sure that the skill has permission to send Alexa events. For details, see Request Access to the Alexa Event Gateway.

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

Account record associated with this directed identifier doesn't exist or has expired. This error can occur if the event was sent too late or with an invalid directed identifier. Verify that the directed identifier and authorization code are correct.

404 Not Found

SKILL_NOT_FOUND_EXCEPTION

Skill ID associated with this token wasn't found. This error occurs when user's access token was generated when the skill was in different stage, such as certification. Try disabling and re-enabling the skill for this user.

413 Payload Too Large

REQUEST_ENTITY_TOO_LARGE_EXCEPTION

Size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send your message with smaller payloads.

429 Too Many Requests

THROTTLING_EXCEPTION

Number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt.

500 Internal Server Error

INTERNAL_SERVICE_EXCEPTION

Error occurred with Alexa, and the message wasn't processed. Resend the message up to three times, with at least a one-second interval between each send attempt. If problems persist, contact Amazon Support.

503 Service Unavailable

SERVICE_UNAVAILABLE_EXCEPTION

Alexa couldn't accept the message. Resend the message up to three times, with at least a one-second interval between each attempt. If the problem persists, contact Amazon Support.

Example 401 Unauthorized response body

The following example shows an error response.

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "The access token is invalid, expired, or malformed."
  }
}

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

StateReport response example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.SecurityPanelController.Alert",
                "name": "delayState",
                "value": {
                    "state": "EXIT_DELAY",
                    "playlistId": "UUID.entry.delay.1"
                },
                "timeOfSample": "2023-05-01T23:23:23.23Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.SecurityPanelController",
                "name": "armState",
                "value": "ARMED_AWAY",
                "timeOfSample": "2023-05-01T23:23:23.23Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2023-05-01T23:23:00.00Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Change reporting

You send an Alexa.ChangeReport event to report changes proactively 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.

Send a ChangeReport when you change the value of the delayState and sirenState properties. Alexa plays the siren alert when the state is ON and stops the alert when the state is OFF. Similarly, Alexa plays the delay alert when the state is ENTRY_DELAY or EXIT_DELAY, and stops the alert when the state is NONE.

ChangeReport event example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint ID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.SecurityPanelController.Alert",
                    "name": "delayState",
                    "value": {
                        "state": "ENTRY_DELAY",
                        "playlistId": "UUID.entry.delay.1"
                    },
                    "timeOfSample": "2023-05-01T23:23:23.23Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.SecurityPanelController.Alert",
                "name": "sirenState",
                "value": {
                    "state": "OFF"
                },
                "timeOfSample": "2023-05-01T22:13:03.23Z",
                "uncertaintyInMilliseconds": 0
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2023-05-01T22:55:00.00Z",
                "uncertaintyInMilliseconds": 23000
            }
        ]
    }
}

Was this page helpful?

Last updated: Aug 23, 2024