Alexa.LockController Interface
The Alexa.LockController capability interface describes the messages used to control lockable endpoints.
For the list of locales that are supported for the LockController interface, see List of Capability Interfaces and Supported Locales.
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
{
"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 an endpoint that supports the Alexa.LockController interface.
{
"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
{
"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
Responseevent 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
{
"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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "DeferredResponse",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"payload": {
"estimatedDeferralInSeconds": 15
}
}
}
Then send a Response event.
{
"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.
de-DE, en-US, ja-JPThe following example shows a customer utterance:
Alexa, unlock my front door.
Unlock directive example
{
"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
Responseevent 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
{
"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.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "DeferredResponse",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"payload": {
"estimatedDeferralInSeconds": 20
}
}
}
Then send a Response event.
{
"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 more information about state reports, see Understand State Reporting.
StateReport response event example
{
"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 more information about change reports, see Understand State Reporting.
ChangeReport event example
{
"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": {}
}
