Alexa.LockController Interface

Implement the Alexa.LockController interface in your Alexa skill so that users can lock and unlock their lockable devices. For more information about security skills, see Smart Home Security Overview.

For the list of languages that the LockController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

When you use the Alexa.LockController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, lock my front door.
Alexa, unlock the back door.

After the customer says an utterance, Alexa sends a corresponding directive to your skill.

Properties

The lockState property

The Alexa.LockController interface uses the lockState property to represent the state of a lock. The following are 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.

LockState property example

Copied to clipboard.

{
  "name": "lockState",
  "value": "LOCKED"
}

Discovery

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

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

Discover response example

The following example shows a Discover.Response message for a smart lock that supports the Alexa.LockController interface.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "<a description that is shown in the Alexa app>",
          "friendlyName": "<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",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Lock directive

Support the Lock directive so that a customer can request that you lock an endpoint.

The following example shows a customer utterance:

Alexa, lock my front door.

Lock directive example

The following example illustrates a Lock directive that Alexa sends to your skill.

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

Lock response event

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

Fast lock example: response event only

Copied to clipboard.

{
  "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.LockController",
        "name": "lockState",
        "value": "LOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Slow lock example: 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.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 15
    }
  }
}

Then send a Response event.

Copied to clipboard.

{
  "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.LockController",
        "name": "lockState",
        "value": "LOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "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 skills, first enable the unlock feature by editing the device in the Alexa app.

The following example shows a customer utterance:

Alexa, unlock my front door.

Unlock directive example

The following example illustrates an Unlock directive that Alexa sends to your skill.

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

Unlock response event

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.

Fast unlock example: response event only

Copied to clipboard.

{
  "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.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Slow unlock example: 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.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Then send a Response event.

Copied to clipboard.

{
  "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.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "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 of 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.

StateReport response event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "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.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes 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

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 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": {}
}