Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Get started
Connect with Matter
Alexa Connect Kit
Add-ons
Certify
Resources
Skip to main content
Implement the 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

The Alexa.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:



Properties

The Alexa.SecurityPanelController interface defines properties for alarms.

ArmState property

The Alexa.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.
ValueDescription
ARMED_AWAYThe security system is active and the occupants are away.
ARMED_STAYThe security system is active and the occupants are present.
ARMED_NIGHTThe security system is active and the occupants are sleeping.
DISARMEDThe security system isn’t active.

Alarm properties

The Alexa.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.
You can use the following alarms.
PropertyDescriptionType
burglaryAlarmThe current state of a burglary alarm; OK or ALARM.Object
carbonMonoxideAlarmThe current state of a carbon monoxide alarm; OK or ALARM.Object
fireAlarmThe current state of a fire alarm; OK or ALARM.Object
waterAlarmThe 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 is ARMED_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 an Alexa.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.



If the user says , Alexa tells the user If you don’t include a list of endpoints in the payload of your 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 sends Disarm 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.
For users who set up a new voice code, the Alexa service stores the voice code securely and asks for the code whenever the user disarms the security system with a voice request. Alexa validates the voice code and then, only when the voice code is correct, sends a 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 support Alexa.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, for SecurityPanelController, include a configuration object that contains the following fields.
FieldDescriptionTypeRequired
supportedAuthorizationTypesThe 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
supportedArmStatesThe 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 a Discover.Response message for a security panel that supports the Alexa.SecurityPanelController interface.

Directives

Alexa sends the following Alexa.SecurityPanelController interface directives to your add-on.

Arm directive

Support the Arm 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:

Arm directive example

The following example illustrates an Arm directive that Alexa sends to your add-on.

Arm with bypass directive example

The following example illustrates an Arm 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 the Arm directive.
FieldDescriptionType
armStateArm state to set for the endpoint.armState value
bypassTypeType 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 an Arm 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.
The following example shows an Arm response with active ALARM.
The following example shows an Arm response with bypassed endpoints.

Arm response payload

The following table shows the payload details for the Arm response.
FieldDescriptionTypeRequired
exitDelayInSecondsNumber 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
bypassedEndpointsEndpoints 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 an Arm 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 the Disarm 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:

Disarm directive example

The following example illustrates a Disarm directive that Alexa sends to your add-on.

Disarm directive payload

The following table shows the payload details for the Disarm directive.
FieldDescriptionType
authorizationThis 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 a Disarm 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.
The following example shows a Disarm response with active ALARM.

Disarm directive error handling

If you can’t handle a Disarm directive successfully, respond with an Alexa.SecurityPanelController.ErrorResponse event.

State reporting

Support the ReportState directive so that users can ask about the status of their security panel. The following examples show user utterances:
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 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 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. You should proactively report alarm conditions for the alarms that you support.

ChangeReport event example for manual disarm

ChangeReport event example with active alarm

Last modified on September 30, 2026