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
{
"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.
{
"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
{
"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.
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
{
"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 details about state reports, see Understand State and Change 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 details about change reports, see Understand State and Change 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": {}
}