Merci de votre visite. Cette page est disponible en anglais uniquement.

Alexa.SecurityPanelController Interface

The Alexa.SecurityPanelController interface describes messages that you can use to develop Alexa skills for security systems. Customers can use your skill to arm and disarm their security system, and you can report alarm conditions to your customers.

If your security system uses contact and motion sensors, your skill can also implement the Alexa.ContactSensor and Alexa.MotionSensor interfaces for a unified customer experience.

For the list of locales that are supported for the SecurityPanelController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.SecurityPanelController interface, the voice interaction model is already built for you. The following examples show some customer utterances, where "my home" is the name that the customer assigned to their security system device:

Alexa, arm my home in away mode.
Alexa, arm my home.
Alexa, disarm my home.
Alexa, is my home armed?

After the customer says one of these utterances, Alexa sends a corresponding directive or state request to your skill.

Properties

The armState property

The Alexa.SecurityPanelController interface uses the armState property as the primary property.

You can use the following values for armState. The values are strings.

Value Description
ARMED_AWAY Indicates that the security system is active and the occupants are away.
ARMED_STAY Indicates that the security system is active and the occupants are present.
ARMED_NIGHT Indicates that the security system is active and the occupants are sleeping.
DISARMED Indicates that the security system is not active.

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

You can use the following alarms.

Property Description Type
burglaryAlarm Indicates the current state of a burglary alarm; OK or ALARM. Object
carbonMonoxideAlarm Indicates the current state of a carbon monoxide alarm; OK or ALARM. Object
fireAlarm Indicates the current state of a fire alarm; OK or ALARM. Object
waterAlarm Indicates the current state of a water alarm; OK or ALARM. Object

Burglary alarm example

{
    "name": "burglaryAlarm",
    "value": {
        "value": "OK"
    }
}

Security system considerations

Considerations for arming a security system

If the armed state of a security system is ARMED_AWAY, meaning that the occupants are away, the customer must disarm the security system before changing to another armed state. For example, if the customer is away, comes home, and wants to change the armed state to ARMED_NIGHT, the customer 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 error type AUTHORIZATION_REQUIRED error. For more information, see Alexa.SecurityPanelController.ErrorResponse.

Considerations for PIN code support

When your skill controls a security system that already uses four-digit PIN codes, and your backend system can validate PIN codes, your skill can allow customers to disarm the security system by voice using their existing PIN codes.

Considerations for disarming a security system

Customers must opt in to the disarm by voice feature. Customers do this in the Alexa app when they connect their device to Alexa. When a customer opts-in, Alexa sends Disarm directives to your skill, otherwise it does not. When a customer opts in, they set up a voice code in one of the following ways:

  • If your skill does not support existing PIN codes, the customer must set up a new voice code.
  • If your skill supports existing PIN codes, the customer can set up a new voice code or use their four-digit PIN codes that are already associated with the security system.

For customers who set up a new voice code, the Alexa service stores the voice code securely and asks for it whenever the customer 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 skill.

For customers who use existing PIN codes, Alexa asks for a PIN code whenever the customer 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 is not valid, your skill must respond with an error of type UNAUTHORIZED. For more information, see

Considerations for state reporting about a security system

When you respond to a directive, include a context object in your response. In the context object, at a minimum, include the values of all properties that changed. We recommend that you specify the state of all the properties of the endpoint, including the properties that didn't change, to help improve the customer experience. For more information, see Understand State Reporting for a Smart Home Skill.

Discovery

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

Set retrievable to true for all of the properties that you will report when Alexa sends your skill 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.

Discovery payload details

Property Description Type Required
supportedAuthorizationTypes Use this field only when your skill controls a security system that supports four digit PIN codes and your backend systems can validate those PIN codes. The only valid type is FOUR_DIGIT_PIN. Array No
supportedArmStates The states that the security system supports. By default, Alexa assumes that the security system supports all states. An array of armState property values. No

Discovery example

The following example shows a Discover.Response message for a security panel endpoint.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the security panel endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "friendlyName": "<security panel name, displayed in the Alexa app>",
          "description": "<a description that is shown in the Alexa app>",
          "displayCategories": [
            "SECURITY_PANEL"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SecurityPanelController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "armState"
                  },
                  {
                    "name": "burglaryAlarm"
                  },
                  {
                    "name": "fireAlarm"
                  }                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedAuthorizationTypes": [
                  {
                    "type": "FOUR_DIGIT_PIN"
                  }
                ],
                "supportedArmStates": [
                  {
                    "value": "ARMED_AWAY"
                  },
                  {
                    "value": "ARMED_STAY"
                  },
                  {
                    "value": "DISARMED"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}

Directives

Arm directive

Support the Arm directive so that customers 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 more information, see Security system considerations.

The following example shows a customer utterance:

Alexa, arm my home in away mode.

Arm directive payload details

Property Description Type
armState Indicates the arm state that the customer is requesting for the endpoint. An armState property string value.

Arm directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "Arm",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "armState": "ARMED_AWAY"
    }
  }
}

Arm response event

If you handle an Arm directive successfully, respond with an Arm.Response event. In the context object, include the values of all properties that changed.

Arm.Response event payload details

Field Description Type Required
exitDelayInSeconds Indicates the number of seconds that the security system delays to allow the occupants to exit before it arms. For no delay, set this value to 0. An integer between 0 and 255. No

Arm.Response event example

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "Arm.Response",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "an OAuth2 bearer token"
      },
      "endpointId": "the endpoint identifier of the endpoint"
    },
    "payload": {
      "exitDelayInSeconds": 0
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.SecurityPanelController",
        "name": "armState",
        "value": "ARMED_AWAY",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Arm.Response event example with ALARM

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "Arm.Response",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "an OAuth2 bearer token"
      },
      "endpointId": "the endpoint identifier of the endpoint"
    },
    "payload": {
      "exitDelayInSeconds": 0
    }
  },
  "context": {
    "properties": [
        {
            "namespace": "Alexa.SecurityPanelController",
            "name": "burglaryAlarm",
            "value": {
                "value": "ALARM"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        },
        {
            "namespace": "Alexa.SecurityPanelController",
            "name": "armState",
            "value": "ARMED_AWAY",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
        }
    ]
  }
}

Arm directive error handling

If you can't handle an Arm directive successfully, respond with an Alexa.SecurityPanelController.ErrorResponse event.

Disarm directive

Support the Disarm directive so that customers 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 skill if the customer opts in to the disarm feature. For more information, see Security system considerations.

The following example shows a customer utterance:

Alexa, disarm my home.

Disarm directive payload details

Property Description Type
authorization This property is present only when your skill supports existing PIN codes and the customer chooses to use existing pin codes. You must validate the PIN before you disarm the security system. When the customer disarms with an Alexa voice code, this property is not present. Object

Disarm directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "Disarm",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
          "type": "BearerToken",
          "token": "<an OAuth2 bearer token>"
        },
        "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "authorization": {
        "type": "FOUR_DIGIT_PIN",
        "value": "1234"
      }
    }
  }
}

Disarm response event

If you handle a Disarm directive successfully, respond with a standard Alexa.Response event. In the context object, include the values of all properties that changed. For more information, see Alexa.Response Interface.

Alexa.Response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
          "type": "BearerToken",
          "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
      "properties": {
          "namespace": "Alexa.SecurityPanelController",
          "name": "armState",
          "value": "DISARMED",
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 0
      }
  }
}

Disarm directive error handling

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