Alexa.LockController Interface

The Alexa.LockController interface describes the messages used to control lockable endpoints.

Directives
- Lock
- Unlock
Properties and Events
Additional Sample Code

Directives

This control and query directives in this interface are supported in skills that target the following languages:

English (US)
English (UK)
German

See Develop Smart Home Skills in Multiple Languages for more information.

Lock

Request to lock an endpoint.

“Alexa, lock my “endpoint name”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

Payload details

Field	Description	Type	Required
None	No required or optional fields in the payload.	N/A	N/A

Unlock

Request to unlock an endpoint.

Note: Requests to unlock are currently not supported.

“Alexa, unlock my “endpoint name”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

Payload details

Field	Description	Type	Required
None	No required or optional fields in the payload.	N/A	N/A

Properties and Events

For this interface, you must either reply:

Synchronously, which means you send a Response event to Alexa from the Lambda function.
Asynchronously, which means you send a Response event to the Alexa event gateway. When you reply asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.

When you send a Response, you should include the state of reportable properties in the context of the message.

When you are deciding how to reply to a Lock or Unlock directive, you should consider how fast the hardware device can complete the request. If the hardware is fast, you can respond with an Response event that indicates the lock has changed state to unlocked or locked. Currently a fast lock is considered one that complete the request in 5 seconds or less.

For slower hardware, you should send a Alexa.DeferredResponse with the estimatedDeferralInSeconds specified, followed by an Response to the Alexa event gateway when the action completes. You include the correlation token sent with the request in both of these messages. With this message flow, Alexa can respond to the customer appropriately.

Reportable Properties

Property Name	Type	Description
`lockState`	LockState	Indicates the current lock state of the device. A string with the following supported values: “LOCKED”, “UNLOCKED”, or “JAMMED”.

DeferredResponse

For slower locks:

Send an DeferredResponse event to indicate the request is in process with the estimatedDeferralInSeconds specified.
Follow this with a Response event to the Alexa event gateway. This event must contain a context object that indicates the new value of the lockState property after the request completes, such as LOCKED or JAMMED.

Both of these events must include the correlation token from the request.

Example Alexa.DeferredResponse for Slower Hardware:

The following example shows the deferred response event for a slower lock.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Example Response for Slower Hardware:

The following example shows the response event for a lock request to a slower lock. This event must include the correlation token from the original request and provides the value of the lockState property.

{
  "context": {
    "properties": [
          {
            "namespace": "Alexa.LockController",
            "name": "lockState",
            "value": "LOCKED",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
     ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
    }
  }
}

Response

Return an Response synchronously for a lock that typically completes the lock or unlock action in 5 seconds or less.

Example Response:

The following example shows the response to an lock request that completed in under 5 seconds.

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.LockController",
      "name": "lockState",
      "value": "LOCKED",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Error.Response for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

LockController