Alexa.SecurityPanelController Interface

Use the Alexa.SecurityPanelController interface to describe a security panel endpoint. A security panel endpoint represents a device that controls a security system.

Discovery

To notify Alexa of your security panel endpoint, your skill sends one of the following messages:

When you notify Alexa of your security panel endpoint, you must:

  • Include "displayCategories": ["SECURITY_PANEL"] to indicate that the endpoint is a security panel.
  • Set "retrievable": true for all of the reportable state properties. This means that all of these properties are sent in a StateReport event whenever your skill receives a ReportState directive.
  • Include a configuration object in the endpoints.capabilities section of the payload.

You should also set "proactivelyReported": true for all of the reportable state properties. This means that all of these properties are sent in ChangeReport events whenever the state of the endpoint changes for any reason.

(Optional) Indicate support for existing PIN codes

When your skill controls a security system that supports existing four digit PIN codes, and your backend systems can validate those PIN codes, your skill can allow customers to disarm the security system by voice using their existing PIN codes. To do so, in your skill's discovery message for the security panel endpoint, send a supportedAuthorizationTypes object with the type field set to FOUR_DIGIT_PIN, as shown in the following example.

Example discovery response

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

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "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"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedAuthorizationTypes": [
                  {
                    "type": "FOUR_DIGIT_PIN"
                  }
                ],
                "supportsArmInstant": true,
                "supportedArmStates": [
                  {
                    "value": "ARMED_AWAY"
                  },
                  {
                    "value": "ARMED_STAY"
                  },
                  {
                    "value": "DISARMED"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}

Configuration object

The following table describes the properties (fields) in the configuration object.

Property Description Type
supportedAuthorizationTypes Optional. 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. For more information, see (Optional) Indicate support for existing PIN codes. Array of objects. Each object's type value is a string. The only valid type is FOUR_DIGIT_PIN.
supportsArmInstant Optional. Indicates whether the security system supports immediate arming with no exit delay. When this field is not present, the default value is false. Boolean
supportedArmStates Optional. Indicates the arm states that the security system supports. Used to validate whether the arm state that a customer requests is valid for the security system. When this field is not present, Alexa assumes that the security system supports all the valid arm states. Array of objects. Each object's type value is a string. Valid types are ARMED_AWAY, ARMED_STAY, ARMED_NIGHT, and DISARMED.

Directives

Skills that control security panel endpoints must support two directives, Arm and Disarm.

Example utterances

The examples in the following sections show some utterances that the Alexa.SecurityPanelController interface supports.

To arm the security system

To arm a security system, customers can use utterances like the following.

User: Alexa, arm device name in mode name mode.
User: Alexa, arm device name.

For example, the following utterances arm a security system named my home. When the customer doesn't provide a mode, Alexa defaults to ARMED_STAY mode.

User: Alexa, arm my home in away mode.
User: Alexa, arm my home.

To disarm the security system

To disarm a security system, customers can use an utterance like the following.

User: Alexa, disarm device name.

For example, the following utterance disarms a security system named my home.

User: Alexa, disarm my home.

To query the state of the security system

To query the state of a security system, customers can use an utterance like the following.

User: Alexa, is device name armed?

For example, the following utterance queries the state of a security system named my home.

User: Alexa, is my home armed?

Arm

Alexa sends an Arm directive to your skill when a customer uses Alexa to arm a security system.

The following example shows an Arm directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "Arm",
      "messageId": "2bfeb157-89b1-40f3-ba50-677e233b3312",
      "correlationToken": "an opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "an OAuth2 bearer token"
      },
      "endpointId": "the identifier of the target endpoint",
      "cookie": {}
    },
    "payload": {
      "armState": "ARMED_AWAY",
      "isArmInstant": true
    }
  }
}

Arm payload

The following table describes the properties (fields) in the payload of an Arm directive.

Property Description Type
armState Required (always present). Indicates the desired arm state of the endpoint. String. For the list of supported arm states, see supportedArmStates in the configuration object.
isArmInstant Optional (might not be present). Indicates whether to arm immediately with no exit delay. Boolean

Disarm

Customers must opt in to using the disarm by voice feature. Customers do this in the Alexa app, either during guided discovery or after discovering the security panel endpoint separately.

When a customer does not opt in, Alexa does not send Disarm directives to your skill.

When a customer does opt in, they must set up a voice code. Depending on whether your skill indicated support for existing PIN codes, customers set up a voice code in one of the following ways:

  • If your skill indicated support for existing PIN codes, customers can choose one of the following options:
    • Use their existing four digit PIN codes that are already associated with the security system.
    • Set up a new voice code.
  • If your skill did not indicate support for existing PIN codes, the customer must set up a new voice code.

For customers who use existing PIN codes, Alexa asks for a PIN code whenever the customer disarms the security system with a voice request. Alexa includes the PIN code in the Disarm directive that is sent to the skill. Your backend systems should validate the PIN code before disarming the security system. When the PIN code is not valid, your skill should respond with an ErrorResponse event of type UNAUTHORIZED.

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.

The following example shows a Disarm directive for a skill that supports existing PIN codes.

{
  "directive": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "Disarm",
      "messageId": "2bfeb157-89b1-40f3-ba50-677e233b3312",
      "correlationToken": "an opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "an OAuth2 bearer token"
      },
      "endpointId": "the identifier of the target endpoint",
      "cookie": {}
    },
    "payload": {
      "authorization": {
        "type": "FOUR_DIGIT_PIN",
        "value": "7768"
      }
    }
  }
}

Disarm payload

The following table describes the properties (fields) in the payload of a Disarm directive.

Property Description Type
authorization Optional (might not be present). This field is present only when the skill indicated support for existing PIN codes and the customer chose to use existing pin codes. In that case, Alexa sends the PIN code to the skill to validate before disarming. When the customer disarms with an Alexa voice code, this field is not included. String consisting of four single-digit numbers.

Properties and events

The following table describes the reportable state properties defined by this interface.

Property Description Type
armState Indicates the current arm state of the security system. String. For the list of supported arm states, see supportedArmStates in the configuration object.
burglaryAlarm Indicates the current state of the burglary alarm. Use this property for security panels that integrate with a burglary alarm. String. Valid values are OK and ALARM.
fireAlarm Indicates the current state of the fire alarm. Use this property for security panels that integrate with a fire alarm. String. Valid values are OK and ALARM.
carbonMonoxideAlarm Indicates the current state of the carbon monoxide alarm. Use this property for security panels that integrate with a carbon monoxide alarm. String. Valid values are OK and ALARM.
waterAlarm Indicates the current state of the water alarm. Use this property for security panels that integrate with a water alarm. String. Valid values are OK and ALARM.

Arm.Response event

After your skill receives an Arm directive, it must respond with one of the following:

  • A synchronous Arm.Response event. Send this event after the endpoint transitions to the desired arm state and before performing exit delay.
  • A DeferredResponse event. Send this event after your skill receives the directive to indicate that you'll send a response later with an asynchronous Arm.Response event.

In either case, there is a hard limit of 20 seconds before Alexa times out.

When your skill receives an Arm directive whose armState matches the current state of the security system, send an Arm.Response event indicating that the request was handled successfully. Do not send an error response in this case.

The following example shows an Arm.Response event.

{
  "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"
    },
    "context": {
      "properties": [
        {
          "namespace": "Alexa.SecurityPanelController",
          "name": "armState",
          "value": "ARMED_AWAY",
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 0
        }
      ]
    },
    "payload": {
      "exitDelayInSeconds": 0
    }
  }
}

Arm.Response payload

The following table describes the properties (fields) in the payload of an Arm.Response event.

Property Description Type
exitDelayInSeconds Optional. Indicates the number of seconds that the security system will be in exit delay. If there is no exit delay, set this value to 0. If the exit delay is not known, omit this value. Integer. Minimum value is 0, maximum value is 255.

Alexa.Response event

After your skill receives a Disarm directive and the security system is successfully disarmed, your skill must respond with an Alexa.Response event.

When your skill receives a Disarm request for a security system that is already disarmed, send an Alexa.Response event to indicate that the request was handled successfully. Do not send an error response in this case.

The following example shows an Alexa.Response event.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "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"
    },
    "context": {
      "properties": {
        "namespace": "Alexa.SecurityPanelController",
        "name": "armState",
        "value": "DISARMED",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    },
    "payload": {}
  }
}

ErrorResponse event

When your skill cannot successfully handle an Arm or Disarm directive, it must send an ErrorResponse event instead of an Arm.Response or Alexa.Response. Your skill can send two kinds of error response events:

  • An Alexa.SecurityPanelController.ErrorResponse, as described in the following example and table.
  • A generic Alexa.ErrorResponse. For more information, see Alexa.ErrorResponse.

Example Alexa.SecurityPanelController.ErrorResponse event

{
  "event": {
    "header": {
      "namespace": "Alexa.SecurityPanelController",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "an OAuth2 bearer token"
      },
      "endpointId": "the endpoint identifier of the endpoint"
    },
    "payload": {
      "type": "UNCLEARED_ALARM",
      "message": "Unable to arm or disarm the security panel because it is in alarm status."
    }
  }
}

The following table describes the valid type values in the payload of an Alexa.SecurityPanelController.ErrorResponse event.

Type Description
AUTHORIZATION_REQUIRED Use this error type when the security system's current state is ARMED_AWAYand your skill receives an Arm directive that requests to change the state to ARMED_STAY or ARMED_NIGHT. For more information, see the Arm directive.
BYPASS_NEEDED The security panel has open zones that must be bypassed for the requested operation to succeed.
NOT_READY The security panel is not ready for arming and disarming. Use this error type when a customer tries to control the security panel while it's in installer mode.
UNAUTHORIZED The PIN code is not correct. For more information, see indicate support for existing PIN codes.
UNCLEARED_ALARM The security panel has an uncleared alarm. Use this error type only in response to an Arm directive. A Disarm directive should clear the alarm.
UNCLEARED_TROUBLE The security panel has an uncleared trouble condition.