Alexa.LockController Interface 3

Implement the Alexa.LockController interface in your Alexa add-on so that users can lock and unlock their lockable devices. For more details about security add-ons, see Smart Home Security Overview. For the list of languages that the LockController 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

When you use the Alexa.LockController interface, the Alexa service provides the voice interaction model for you. 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:

Reportable properties

The Alexa.LockController interface uses the lockState property to represent the state of a lock. The following table shows the valid lock state values:

Value	Description
`LOCKED`	The device is currently locked.
`UNLOCKED`	The device is currently unlocked.
`JAMMED`	The lock can’t transition to locked or unlocked because the locking mechanism is jammed.

Discovery

You describe endpoints that support Alexa.LockController using the standard discovery mechanism described in Alexa.Discovery. Set retrievable to true for all interfaces and properties that you report when Alexa sends your add-on a state report request. Set proactivelyReported to true for interfaces and properties that you proactively report to Alexa in a change report. Use SMARTLOCK for the 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.

Discover response example

The following example shows a Discover.Response message for a smart lock that supports the Alexa.LockController 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 of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Your device name, displayed in the Alexa app, for example Front Door>",
          "displayCategories": ["SMARTLOCK"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.LockController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lockState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

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

Lock directive

Support the Lock directive so that a customer can request that you lock an endpoint. The following examples show user utterances:

Lock directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {}
  }
}

Lock directive payload

The Lock directive doesn’t define any payload parameters.

Lock response

If you handle a Lock directive successfully, respond depending on the speed with which your hardware can complete the task.

If your hardware can lock in 5 seconds or fewer, send an Alexa.Response event.
If your hardware takes more than 5 seconds to lock, first send a synchronous DeferredResponse event, and then send a Response event when the lock completes.

In either case, you can send the Response event synchronously or asynchronously. If you send the Response asynchronously, include a correlation token and a scope with an authorization token. Specify the value of the lockState property in the context of your response.

Lock response example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "LOCKED",
        "timeOfSample": "2017-02-03T16:20:00.00Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Slow lock example with deferred response and response

The following example shows the two responses to a lock directive that completes in more than 5 seconds. First send a synchronous DeferredResponse event. Optionally include estimatedDeferralInSeconds, the approximate time before you send your second response, in seconds.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 15
    }
  }
}

Then send a Response event.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "LOCKED",
        "timeOfSample": "2017-02-03T16:20:00.00Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Lock directive error handling

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

Unlock directive

Support the Unlock directive so that a customer can request that you unlock an endpoint. By default, you can’t unlock a device. When you test your lockable endpoint add-ons, first enable the unlock feature by editing the device in the Alexa app. The following examples show user utterances:

Unlock directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {}
  }
}

Unlock directive payload

The Unlock directive doesn’t define any payload parameters.

Unlock response

If you handle an Unlock directive successfully, respond depending on the speed with which your hardware can complete the task.

If your hardware can unlock in 5 seconds or fewer, send a Response event.
If your hardware takes more than 5 seconds to unlock, first send a synchronous DeferredResponse event, and then send a Response event when the unlock completes.

In either case, you can send the Response event synchronously or asynchronously. Specify the value of the lockState property in the context of your response.

Unlock response example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:00.00Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Slow unlock example with deferred response and response

The following example shows the two responses to an unlock directive that completes in more than 5 seconds. First send a synchronous DeferredResponse event. Optionally include estimatedDeferralInSeconds, the approximate time before you send your second response, in seconds.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Then send a Response event.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:00.00Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Unlock directive error handling

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

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. The following examples show some user utterances:

StateReport response example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "JAMMED",
        "timeOfSample": "2017-02-03T16:20:00.00Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

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.

ChangeReport event example

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.LockController",
            "name": "lockState",
            "value": "LOCKED",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 1000
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T06:18:00Z",
    "uncertaintyInMilliseconds": 0
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Reportable properties

Discovery

Discover response example

Directives

Lock directive

Lock directive example

Lock directive payload

Lock response

Lock response example

Slow lock example with deferred response and response

Lock directive error handling

Unlock directive

Unlock directive example

Unlock directive payload

Unlock response

Unlock response example

Slow unlock example with deferred response and response

Unlock directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Reportable properties

​Discovery

​Discover response example

​Directives

​Lock directive

​Lock directive example

​Lock directive payload

​Lock response

​Lock response example

​Slow lock example with deferred response and response

​Lock directive error handling

​Unlock directive

​Unlock directive example

​Unlock directive payload

​Unlock response

​Unlock response example

​Slow unlock example with deferred response and response

​Unlock directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Reportable properties

Discovery

Discover response example

Directives

Lock directive

Lock directive example

Lock directive payload

Lock response

Lock response example

Slow lock example with deferred response and response

Lock directive error handling

Unlock directive

Unlock directive example

Unlock directive payload

Unlock response

Unlock response example

Slow unlock example with deferred response and response

Unlock directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics