Alexa.LockController Interface 3

Implement the Alexa.LockController interface in your Alexa skill so that users can lock and unlock their lockable devices. For more details 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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

When you use the Alexa.LockController interface, the Alexa service provides the voice interaction model for you. After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your skill.

The following examples show some user utterances:

Alexa, lock my front door.
Alexa, unlock the back door.
Alexa, is my door locked?
Alexa, is my door unlocked?

Alexa, verrouille la porte d'entrée.
Alexa, déverrouille la porte arrière.
Alexa, est-ce que la porte est verrouillée?
Alexa, est-ce que la porte est déverrouillée?

Alexa, schließe meine Haustür ab.
Alexa, entsperre die Hintertür.
Alexa, ist meine Tür verschlossen?
Alexa, ist meine Tür aufgeschlossen?

Alexa, chiudi a chiave la mia porta d'ingresso.
Alexa, sblocca la porta sul retro.
Alexa, la mia porta è chiusa a chiave?
Alexa, la mia porta è aperta?

アレクサ、玄関をロックして
アレクサ、裏口を開けて
アレクサ、玄関の鍵は閉まっている？
アレクサ、玄関の鍵は開いている？

Alexa, tranque minha porta da frente.
Alexa, destranque a porta traseira.
Alexa, a minha porta está trancada?
Alexa, a minha porta está destrancada?

Alexa, bloquea la puerta de mi casa.
Alexa, desbloquea la puerta trasera.
Alexa, ¿mi puerta está bloqueada?
Alexa, ¿mi puerta está desbloqueada?

Reportable properties

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

Discovery

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

Set retrievable to true for all 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.

For connected vehicles that use Alexa user identification, include directiveConfigurations in your discovery response to configure the authentication confidence level and policy name. For details, see directiveConfigurations.

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": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Your 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.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.LockController interface directives to your skill.

Lock directive

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

The following examples show user utterances:

Alexa, lock my front door.

Alexa, verrouille la porte d'entrée.

Alexa, schließe meine Haustür ab.

Alexa, chiudi a chiave la mia porta d'ingresso.

アレクサ、玄関をロックして

Alexa, tranque minha porta da frente.

Alexa, bloquea la puerta de mi casa.

Lock directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {}
  }
}

Lock response

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.

Lock response example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 with 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": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 15
    }
  }
}

Then send a Response event.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 examples show user utterances:

Alexa, unlock the back door.

Alexa, déverrouille la porte arrière.

Alexa, entsperre die Hintertür.

Alexa, sblocca la porta sul retro.

アレクサ、裏口を開けて

Alexa, destranque a porta traseira.

Alexa, desbloquea la puerta trasera.

Unlock directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {}
  }
}

Unlock response

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.

Unlock response example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 with 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": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

Then send a Response event.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 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.

The following examples show some user utterances:

Alexa, is my door locked?
Alexa, is my door unlocked?

Alexa, est-ce que la porte est verrouillée?
Alexa, est-ce que la porte est déverrouillée?

Alexa, ist meine Tür verschlossen?
Alexa, ist meine Tür aufgeschlossen?

Alexa, la mia porta è chiusa a chiave?
Alexa, la mia porta è aperta?

アレクサ、玄関の鍵は閉まっている？
アレクサ、玄関の鍵は開いている？

Alexa, a minha porta está trancada?
Alexa, a minha porta está destrancada?

Alexa, ¿mi puerta está bloqueada?
Alexa, ¿mi puerta está desbloqueada?

StateReport response example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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 report changes proactively 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": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 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": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2017-02-03T16:20:50Z",
    "uncertaintyInMilliseconds": 0
  }
}

Last updated: Feb 16, 2023