Alexa.SecurityPanelController interface in your Alexa add-on so that users can arm and disarm security systems, and so that you can report alarm conditions to your users. For details about security add-ons, see Smart Home Security Overview.
If your security system uses contact and motion sensors, you can also implement the Alexa.ContactSensor and Alexa.MotionSensor interfaces for a unified user experience.
If your security camera or video doorbell supports mode-based settings, such as “Away” mode, you can implement a virtual security panel so that users can control their video modes in the Alexa app and on Alexa-enabled devices. For security purposes, users must set up a PIN to manually disable or change these modes with Alexa.
For the list of languages that the Alexa.SecurityPanelController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Utterances
TheAlexa.SecurityPanelController interface uses the pre-built voice interaction model. After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your add-on.
The following examples show some user utterances, where “my home” is the name that the user assigned to their security system device:
- English (All)
- French (All)
- German
- Italian
- Japanese
- Portuguese
- Spanish (All)
Properties
TheAlexa.SecurityPanelController interface defines properties for alarms.
ArmState property
TheAlexa.SecurityPanelController interface uses the armState property as the primary property. You identify the arm states that you support in your discovery response. At a minimum, Amazon recommends that you support DISARMED and at least one ARMED state.
You can use the following values for armState. The values are strings.
| Value | Description |
|---|---|
ARMED_AWAY | The security system is active and the occupants are away. |
ARMED_STAY | The security system is active and the occupants are present. |
ARMED_NIGHT | The security system is active and the occupants are sleeping. |
DISARMED | The security system isn’t active. |
Alarm properties
TheAlexa.SecurityPanelController interface uses alarm properties to represent different types of alarms and the current status of each. Use these alarm properties in the context object when you respond to directives or report state to Alexa. Use ALARM as the property value to indicate that an alarm condition is happening.
Support for alarms is optional. You identify the alarms that you support in your discovery response.
The following example shows a burglary alarm.
| Property | Description | Type |
|---|---|---|
burglaryAlarm | The current state of a burglary alarm; OK or ALARM. | Object |
carbonMonoxideAlarm | The current state of a carbon monoxide alarm; OK or ALARM. | Object |
fireAlarm | The current state of a fire alarm; OK or ALARM. | Object |
waterAlarm | The current state of a water alarm; OK or ALARM. | Object |
Security system considerations
Arming a security system
If the armed state of a security system isARMED_AWAY, meaning that the occupants are away, the user must disarm the security system before changing to another armed state. For example, if the user is away, comes home, and wants to change the armed state to ARMED_NIGHT, the user must disable the security system first, and then set the new armed state. If you receive an Arm directive that violates this rule, respond with an AUTHORIZATION_REQUIRED error. For more details, see Alexa.SecurityPanelController.ErrorResponse.
Bypass by voice option
When a user tries to arm their security system, you might not be able to satisfy the request. For example, when a user tries to arm their system, but a window that has a contact sensor is open. An open sensor represents an error that the user must correct or bypass before you can arm the security system. In that case you reject the request to arm the system, and send anAlexa.SecurityPanelController.ErrorResponse with type BYPASS_NEEDED.
If you want users to bypass errors by using voice commands, include a list of the endpoints that need bypassing in the payload of your BYPASS_NEEDED response. After Alexa receives a BYPASS_NEEDED response with a list of endpoints in the payload, Alexa prompts the user to bypass the errors. For more details, see bypass needed example.
The following example shows a sample conversation when you include a list of the endpoints that need bypassing in the payload of your BYPASS_NEEDED response. “My home” is the name that the user assigned to their security system device.
- English (All)
BYPASS_NEEDED error response, Alexa tells the user
Disarming a security system
Users must opt in to the disarm by voice feature. Users do this in the Alexa app when they connect their device to Alexa. When a user opts in, Alexa sendsDisarm directives to your add-on. When a user opts in, they set up a voice code in one of the following ways:
- If your add-on doesn’t support existing PIN codes, the user must set up a new voice code.
- If your add-on supports existing PIN codes, the user can set up a new voice code or use the four-digit PIN codes that are already associated with the security system.
Disarm directive to your add-on.
For users who use existing PIN codes, Alexa asks for a PIN code whenever the user disarms the security system with a voice request. Your backend systems must validate the PIN code before you disarm the security system. When the PIN code isn’t valid, your add-on must respond with an error of type UNAUTHORIZED. For details, see Alexa.SecurityPanelController.ErrorResponse.
PIN code support
When your add-on controls a security system that already uses four-digit PIN codes, and your backend system can validate PIN codes, your add-on can allow users to use their existing PIN code to disarm the security system by voice.Discovery
You describe endpoints that supportAlexa.SecurityPanelController 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 properties that you proactively report to Alexa in a change report. You should proactively report alarm conditions.
Identify the alarms that you support, such as burglary alarm and fire alarm, in the supported properties field. Support for alarms is optional. For details, see alarm properties.
Use SECURITY_PANEL for the display category. For the full list of display categories, see display categories.
Configuration object
In addition to the usual discovery response fields, forSecurityPanelController, include a configuration object that contains the following fields.
| Field | Description | Type | Required |
|---|---|---|---|
supportedAuthorizationTypes | The authorization types that your security panel uses. Currently, the only valid type is FOUR_DIGIT_PIN. Include this field only when your add-on controls a security system that supports four-digit PIN codes and your backend systems can validate those PIN codes. | An array of objects. | No |
supportedArmStates | The states that the security system supports. If you don’t include this field, Alexa assumes that the security system supports all states. | An array of armState property values. | No |
Discover response example
The following example shows aDiscover.Response message for a security panel that supports the Alexa.SecurityPanelController interface.
Directives
Alexa sends the followingAlexa.SecurityPanelController interface directives to your add-on.
Arm directive
Support theArm directive so that users can arm their security system. If you receive an Arm directive, and the new armState matches the current armState, respond with a success response, not an error response. However, there are strict requirements for changing armState. For details, see Security system considerations.
The following examples show user utterances:
- English (All)
- French (All)
- German
- Italian
- Japanese
- Portuguese
- Spanish (All)
Arm directive example
The following example illustrates anArm directive that Alexa sends to your add-on.
Arm with bypass directive example
The following example illustrates anArm directive that Alexa sends to your add-on and includes a request to bypass.
Arm directive payload
The following table shows the payload details for theArm directive.
| Field | Description | Type |
|---|---|---|
armState | Arm state to set for the endpoint. | armState value |
bypassType | Type of bypass; currently BYPASS_ALL is the only possible value. This field is only included if applicable. For details, see bypass by voice option. | String |
Arm response
If you handle anArm directive successfully, respond with an Arm.Response event. In the context object, include the values of all relevant properties, and any alarms that are active.
The following example shows an Arm response.
Arm response with active ALARM.
Arm response with bypassed endpoints.
Arm response payload
The following table shows the payload details for theArm response.
| Field | Description | Type | Required |
|---|---|---|---|
exitDelayInSeconds | Number of seconds that the security system waits to allow the occupants to exit before it arms. For no delay, set this value to 0. | Integer between 0 and 255. | No |
bypassedEndpoints | Endpoints that were bypassed. Only include this field if the Arm directive included a bypass request. Include the endpointId for sensors that implement the Alexa.ContactSensor and Alexa.MotionSensor interfaces. For details, see bypass by voice option. | Array of endpoints. | No |
Arm directive error handling
If you can’t handle anArm directive successfully, respond with an Alexa.SecurityPanelController.ErrorResponse event. If you can’t handle an Arm directive successfully because one or more sensors are open, and you want users to be able to bypass the errors by voice, see bypass by voice option.
Disarm directive
Support theDisarm directive so that users can disarm their security system. If you receive a Disarm directive, and the system is already disarmed, respond with a success response, not an error response.
Alexa only sends Disarm directives to your add-on if the user opts in to the disarm feature. For details, see Security system considerations.
The following examples show user utterances:
- English (All)
- French (All)
- German
- Italian
- Japanese
- Portuguese
- Spanish (All)
Disarm directive example
The following example illustrates aDisarm directive that Alexa sends to your add-on.
Disarm directive payload
The following table shows the payload details for theDisarm directive.
| Field | Description | Type |
|---|---|---|
authorization | This property is only included when your add-on supports existing PIN codes and the user chooses to use existing PIN codes. You must validate the PIN before you disarm the security system. When the user disarms with an Alexa voice code, this property isn’t included. | Object |
Disarm response
If you handle aDisarm directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties, and any alarms that are active.
The following example shows a Disarm response.
Disarm response with active ALARM.
Disarm directive error handling
If you can’t handle aDisarm directive successfully, respond with an Alexa.SecurityPanelController.ErrorResponse event.
State reporting
Support theReportState directive so that users can ask about the status of their security panel.
The following examples show user utterances:
- English (All)
- French (All)
- German
- Italian
- Japanese
- Portuguese
- Spanish (All)
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 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
Change reporting
You send aChangeReport 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.
You should proactively report alarm conditions for the alarms that you support.

