Alexa.SecurityPanelController.Alert Interface 1.1

Note: Sign in to the developer console to build or publish your skill.

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.

Important: To avoid customer confusion, configure the same audio files that you use in your security system.

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?

Provide feedback

Last updated: Nov 06, 2024

Alexa.SecurityPanelController.Alert Interface 1.1

Supported alerts

Utterances

Properties and objects

Reportable properties

PlaylistItem object

Discovery

Configuration object

Discover response example

Directives and events

Chime event

Chime event examples

Chime event payload

HTTP status codes

Example 401 Unauthorized response body

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics

Was this page helpful?