Your Alexa Dashboards Settings

Smart Home Skill API Message Reference

The messages exchanged for a smart home skill follow the same basic flow and format. Alexa sends request messages called directives, a skill replies with synchronous or asynchronous events.

A smart home skill implements capability interfaces, which describe the supported directives, events and reportable properties for a functional area such lighting or locks.

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:

In addition, events can contain:

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 asynchronous event in response to a directive.
Correlation tokens are not required for synchronous responses from a Lambda function. When you include a correlation token in an event, you must use the same correlation token that was sent in the directive that caused the event.

If the event is not in response to a request from Alexa, such as a ChangeReport, 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": "access-token-from-Amazon"
      },
      "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 type that is supported.

Scope type value Description Associated field and description
BearerToken Provides an OAuth bearer token for accessing a linked customer account or identifying an Alexa customer. token in the format:
"token" : "tokenvalue"

Context object

Use the Context object to report the state of an endpoint in any event message. A context contains an array of reportable properties objects and their state. When you send a response event with context, you should ensure that the values reported incorporate all the side-effects from handling the directive. In other words, the property values reported must be after any value-changing side effects of handling the directive.

For more details about the context object and state reporting, see State Reporting for more information about the structure of reportable properties, see Property Schemas.

Following is an example context for an endpoint that implements the Alexa.ThermostatController interface.


"context": {
  "properties": [
    {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 25.0,
        "scale": "CELSIUS"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 0
    },
    {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "HEAT",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 0
    }
  ]
}
Field Description
namespace Specifies the interface for the property
name The property name being reported
timeOfSample The time at which the property value was sampled in ISO 8601 format, and specified in UTC. Example: “YYYY-MM-DDThh:mm:ss.sD”
uncertaintyInMilliseconds Indicates the uncertainty of the reported property in milliseconds of elapsed time since the property value was possibly retrieved. For example, if you obtain this value by polling a hardware device every 60 seconds, then the uncertainty in the time of the sampled value would be 60000 in milliseconds.

Payload

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

Smart Home 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

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