Alexa.SecurityPanelController.Alert Interface 1.1

Implement the Alexa.SecurityPanelController.Alert interface in your Alexa add-on so that customers can augment their security system endpoints with sound from Alexa-enabled devices. Your add-on 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 add-on 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 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 add-on 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 add-on supports the Alexa.SecurityPanelController and the Alexa.SecurityPanelController.Alert interfaces, your add-on 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 starts playing the exit delay sound.

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 exit 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 ID 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 ID 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 add-on 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 ID 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 ID 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 allows the customer to 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 ID 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.

{
    "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 add-on sends to Alexa to play a chime alert.

Chime event with default alert

{
    "event": {
        "header": {
            "namespace": "Alexa.SecurityPanelController.Alert",
            "name": "Chime",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "1.1"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Opaque correlation token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "timestamp": "2023-05-01T23:23:23.23Z"
        }
    }
}

Chime event with custom alert

{
    "event": {
        "header": {
            "namespace": "Alexa.SecurityPanelController.Alert",
            "name": "Chime",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "1.1"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Opaque correlation token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "playlistId": "UUID.playlist-chime.1",
            "timestamp": "2023-05-01T23:23:23.23Z"
        }
    }
}

Chime event with list of alerts

{
    "event": {
        "header": {
            "namespace": "Alexa.SecurityPanelController.Alert",
            "name": "Chime",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "1.1"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "Opaque correlation token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "playOrder": [{
                "assetId": "UUID.1"
            }],
            "timestamp": "2023-05-01T23:23:23.23Z"
        }
    }
}

Chime event payload

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

Property	Description	Type	Required
`playlistId`	Unique ID 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 add-on might receive from the Alexa event gateway. If you receive an error, the response body contains the error code and description. 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 not valid 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 expired, malformed, or not valid. Refresh your token and retry the request. If a user disables your add-on, that also invalidates the access token.
`403 Forbidden`	`SKILL_DISABLED_EXCEPTION`	The customer disabled your add-on. Stop sending events for the customer and delete any stored tokens in your system.
`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. Otherwise, the customer never enabled your add-on.
`403 Forbidden`	`INSUFFICIENT_PERMISSION_EXCEPTION`	Token doesn’t have the required permissions. Make sure that the add-on 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 directed identifier that’s not valid. 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 add-on was in different stage, such as certification. Try disabling and re-enabling the add-on 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 error response body

The following example shows an error response.

HTTP/1.1 401 Unauthorized
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "Unique version 4 UUID"
  },
  "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

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

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

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

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 error response body

State reporting

StateReport response example

Change reporting

ChangeReport event example

​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 error response body

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

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

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics