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

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-

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:

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.

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:

Property Description
namespace A string that specifies the category for the message payload. This aligns to the capability interface that contains that directive. For example:
  • Alexa.PowerController
  • Alexa.ThermostatController
name The name of the directive such as TurnOn or TurnOff

messageId

A unique identifier for a single request or response. This is used for tracking purposes and your skill should log this information, although it should not be used to support business logic. Every message must have this field populated. Any string of alphanumeric characters and dashes less than 128 characters is valid, but a version 4 UUID, which is a UUID generated from random numbers, is recommended.

correlationToken

A token that identifies a directive and one or more events associated with it. A correlation token is included in the following message types:
  • A directive from Alexa to the skill.
  • An event in response to a directive.
A response event for a directive request must include the same correlation. If the event is not in response to a request from Alexa, a correlation token must not be provided.
payloadVersion The version of the capability interface applied to this message.

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.

Property Description

scope

A polymorphic object that describes an aspect of the authentication granted to the message exchange. See scope object for more information.

endpointId

A unique identifier. The identifier must be unique across all endpoints for a customer within the domain of the skill. This identifier is provided initially during device discovery, and should consistently identify this device associated with this user.

cookie

A list of key/value pairs associated with the endpoint. These are provided during discovery and are sent in each message for an endpoint.

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.

Field Description Type Required
token The token to validate a customer in the system they account-linked when they enabled the skill. String Yes

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.

Field Description Type Required
token The token for identifying and accessing a linked customer account. String Yes
partition The location target for the request such as a room name or number. String Yes
userId A unique identifier for the user who made the request. You should not rely on userId for identification of a customer. Use token instead. String Yes

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.

Operation Capability Interface
Discover endpoints and report on their capabilities Alexa.Discovery

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.

Operation Message
Respond to a directive request that completes successfully Response
Request a state report Alexa.ReportState
Respond to a state report request Alexa.StateReport
Proactively notify Alexa that an endpoint property has changed Alexa.ChangeReport
Notify Alexa that you are responding asynchronously to a message because the operation will take longer than 8 seconds. (used for locks) Alexa.DeferredResponse
Report whether an endpoint has connectivity Alexa.EndpointHealth

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.

Operation Capability Interface
Turn an endpoint on or off Alexa.PowerController
Set the power level of an endpoint Alexa.PowerLevelController

Door Lock Control and Query Messages

This interface describes messages that query for the current state and change the state of a lock. For more information, see Build Smart Home Skills for Locks.

Operation Capability Interface
Get or set the lock status of an endpoint Alexa.LockController

Temperature Control and Query Messages

This interface describes messages to for getting and setting the temperature of a device. For more information, see Build Smart Home Skills for Thermostats.

Operation Capability Interface
Control thermostats such as setting temperature values and thermostat mode Alexa.ThermostatController
Report the current temperature of an endpoint Alexa.TemperatureSensor

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.

Operation Capability Interface
Adjust the percentage of an endpoint Alexa.PercentageController

Lighting and Tunable Lighting Control Messages

These interfaces describe messages to turn lights on and off and change their settings. For more information, see Build Smart Home Skills for Lights.

Operation Capability Interface
Turn a light on or off Alexa.PowerController
Set the power level of an endpoint Alexa.PowerLevelController
Change the brightness of a light by percentage or to a specific value Alexa.BrightnessController
Change the color of a light Alexa.ColorController
Change the shade of white for a tunable light Alexa.ColorTemperatureController

Front Door Device Messages

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

Operation Capability Interface
Describe an endpoint that is capable of raising doorbell events Alexa.DoorbellEventSource
Support 1-way (half duplex) or 2-way (full duplex) communication over audio and video Alexa.RTCSessionController

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 Build Smart Home Skills for Cameras.

Operation Capability Interface
Retrieve a camera feed Alexa.CameraStreamController

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.

Operation Capability Interface
Turn a device on and off Alexa.PowerController
Change the channel on a device Alexa.ChannelController
Change the input of a playback device Alexa.InputController
Control the playback of device; fast forward, rewind and pause Alexa.PlaybackController
Change the volume in incremental steps Alexa.StepSpeaker
Change the volume to anywhere on a continuous range Alexa.Speaker

Cooking Appliance Control Messages

Operation Capability Interface
Start or stop cooking, change the cooking mode of an appliance Alexa.Cooking
Cook by time Alexa.Cooking.TimeController
Cook using appliance presets Alexa.Cooking.PresetController
Pause or resume cooking Alexa.TimeHoldController

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.

Operation Event
Return an error to Alexa Alexa.ErrorResponse
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment