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
- 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:
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:
|
name
|
The name of the directive such as TurnOn or TurnOff
|
|
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. |
|
A token that identifies a directive and one or more events associated with it. A correlation token is included in the following message types:
|
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 |
---|---|
|
A polymorphic object that describes an aspect of the authentication granted to the message exchange. See scope object for more information. |
|
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. |
|
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 |