Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

Alexa.LockController Interface

The Alexa.LockController 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 one of these utterances, Alexa sends a corresponding directive to your skill.

Discovery

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

Use SMARTLOCK for the display category. For the full list of display categories, see display categories.

Discovery example

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "<message id>"
        },
        "payload": {
            "endpoints":[
                {
                    "endpointId": "<unique ID of the endpoint>",
                    "description": "Smart Lock by Sample Manufacturer",
                    "manufacturerName": "Sample Manufacturer",
                    "friendlyName": "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
                        }
                      }
                    ]
                },
                {
                    "endpointId": "<unique ID of the endpoint>",
                    "description": "Smart Lock by Sample Manufacturer",
                    "manufacturerName": "Sample Manufacturer",
                    "friendlyName": "Back 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
                        }
                      }
                    ]
                }
            ]
        }
    }
}

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:

User: Alexa, lock my front door.

Lock directive payload details

The payload for the Lock directive is empty.

Lock directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "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, send a DeferredResponse event followed by Response event when the lock completes.

You can reply in either of the following ways:

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

Specify the value of the lockState property in the context of your response.

Response event example for a fast lock

The following example shows the response to a lock directive that completes in 5 or fewer seconds.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.LockController",
                "name": "lockState",
                "value": "LOCKED",
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            }
        ]
    },
}

DeferredResponse event example for a slow lock

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Response event example for a slow lock

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

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.

The following example shows a customer utterance:

User: Alexa, unlock my front door.

Unlock directive payload details

The payload for the Unlock directive is empty.

Unlock directive example

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "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, send a DeferredResponse event followed by Response event when the unlock completes.

You can reply in either of the following ways:

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

Specify the value of the lockState property in the context of your response.

Response event example for a fast unlock

The following example shows the response to a unlock directive that completes in 5 or fewer seconds.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.LockController",
                "name": "lockState",
                "value": "UNLOCKED",
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            }
        ]
    },
}

DeferredResponse event example for a slow unlock

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Response event example for a slow unlock

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

Unlock directive error handling

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

Additional Sample Code

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

LockController