Smart Home Skill API Message Reference

Alexa interprets each customer utterance and communicates it to your skill as a request message with a JSON payload that contains an Alexa directive. Your skill responds with a message that contains an Alexa event. In some cases, you can respond synchronously or asynchronously.

A skill that targets smart devices implements capability interfaces, which describe the directives that the skill supports. For example, a lightbulb might support the SetBrightness directive and a security panel might support the Disarm directive.

This topic describes the basic message format and lists capabilities by functional area.

• Message Flow
• Directive and Event Format
• Header object
• Endpoint object
  • Scope object
    • BearerToken scope
    • BearerTokenWithPartition scope
• Payload object
  • Discovery Messages
  • State and Change Reporting Messages
  • Power Control Messages
  • Door Lock Control and Query Messages
  • Temperature Control and Query Messages
  • Percentage Messages
  • Lighting and Tunable Lighting Control Messages
  • Front Door Device Messages
  • Smart Camera Messages
  • Entertainment Control Messages
  • Cooking Appliance Control Messages
  • Error Messages

Message Flow

Alexa sends your skill directives that request something on behalf of the customer. You provide code that responds to directives with events. Your code is hosted as a Lambda function on AWS Lambda (a service offering by Amazon Web Services). When you respond to a directive, you can:

• Reply synchronously with an Alexa.Response event or an error message event from your Lambda function in 8 seconds or less.
• Reply asynchronously with an Alexa.Response event or an error message event to the Alexa event gateway in 8 seconds or less. Note that asynchronous replies are not supported for all interfaces, and this is noted in the interface topics.

-or-

• For slower operations, reply synchronously with a Alexa.DeferredResponse event, and later send the Alexa.Response or an error message event asynchronously to the Alexa event gateway. Note that Alexa.DeferredResponse is currently supported by the LockController interface.

Directive and Event Format

Directives sent to your skill and events sent by your skill back to the Alexa, share the same basic structure.

As a result, both directive and events can contain the following top-level objects:

• Header
• Endpoint
• Payload

When you send an event, you can also include a context object parallel to the event. For more information about context objects, see Understand State Reporting for a Smart Home Skill.

• Context

Header object

A header has a set of expected fields that are the same across message types. These provide different types of identifying information. Following is an example of a typical message header:

"header": {
  "namespace": "Alexa.PowerController",
  "name": "TurnOn",
  "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
  "correlationToken": "abcdef-123456",
  "payloadVersion": "3"
}

A header can contain the following properties:

Endpoint object

An endpoint object identifies the target for a directive and the origin of an event. An endpoint can represent one of the following:

• Physical device
• Virtual device
• Group or cluster of devices
• Software component

In addition, the endpoint contains an authentication token.

• For a directive, the token enables the communication with the device(s) or component represented by the endpoint.
• For an event, the token is only required for events sent to the Alexa event gateway.

Following is an example JSON for a typical message endpoint:

 "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "the identifier of the target endpoint",
      "cookie": {
         "key1": "some information",
         "key": "value pairs received during discovery"
      }
    },

An endpoint object will contain the following properties.

Scope object

A scope is a polymorphic object that provides authorization and identifying info for this message. A scope contains a type field and an additional key/value pair that vary depending on the type. The following table describes the current types that are supported.

BearerToken scope

Provides an OAuth bearer token for accessing a linked customer account or identifying an Alexa customer. Typically used for Smart Home Skills.

BearerToken example

"scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      }

BearerTokenWithPartition scope

Provides an OAuth bearer token for accessing a linked customer account and the physical location where the discovery request should be applied. Typically used for skills that target Alexa for Business. When the scope type is BearerTokenWithPartition, you will see the following fields.

BearerTokenWithPartition example

"scope": {
        "type": "BearerTokenWithPartition",
        "token": "some-access-token",
        "partition": "Room101",
        "userId":"some-user-id"
      }

• In a directive message, the scope contains a token that identifies a customer in your system as a result of account linking. For more information, see Account Linking for Smart Home and Other Domains.
• In an event message, the scope optionally contains a token that identifies a customer to Alexa, which is obtained through the permission process with Login with Amazon (LWA). This token is required for messages to the Alexa event gateway. For more information, see Authenticating a Customer to Alexa with Permissions.

Payload object

The payload for a message can vary depending on what type of message it is. The next few sections describe messages by functional area.

Discovery Messages

This interface describes messages to identify the device and capabilities available to this skill adapter.

State and Change Reporting Messages

These messages are sent to request the state of interface properties, respond to state requests, send change reports or signal Alexa that a response will come later to the event gateway. These messages are formatted the same way regardless of the interface of the request directive.

Power Control Messages

The message types turn a endpoint on or off or control the power level to a device. These messages are typically used by several different types of devices.

Door Lock Control and Query Messages

This interface describes messages that query for the current state and change the state of a lock.

Temperature Control and Query Messages

This interface describes messages to for getting and setting the temperature of a device.

Percentage Messages

This interface describes messages to set, increment or decrement a endpoint by a percentage. These are generic percentages messages, and if possible, you should always use a more specific message type, such as BrightnessController for a light.

Lighting and Tunable Lighting Control Messages

These interfaces describe messages to turn lights on and off and change their settings.

Front Door Device Messages

These interfaces describe messages to communicate with front door devices such as doorbells and intercoms.

Smart Camera Messages

This interface describes messages to query a camera and return a stream URI. For more information and technical requirements for building a smart home skill for cameras, see Smart Home Security Overview.

Entertainment Control Messages

These interfaces describe messages to enable you to interact with entertainment devices and respond to requests for changing the channel of a device, changing the playback of content, or increasing the playback volume. For more information, see Build Smart Home Skills for Entertainment Devices.

Cooking Appliance Control Messages

Error Messages

There are different kinds of errors that can occur.

An interface may define errors specific to that interface, but most error message types are described in the ErrorResponse event.

Unless otherwise noted, error messages are not applicable to appliance discovery, and an error message should never be returned as response to a discovery directive.