Home > Alexa > Alexa Skills Kit

Smart Home Skill Message Guide

intro

Directives and event messages are formatted in JSON and share a similar structure. This topic describes the general message flow and the structure of directive and event messages.

Authentication

Authentication for a smart home skill uses OAuth2.0, and every smart home skill requires account linking. A device cloud must support the authorization code grant flow type. As a result, each request sent contains a scope object with an OAuth bearer token in the request, which you can use to authorize that customer on their device cloud account.

Make sure that your OAuth solution has white-listed the OAuth redirect endpoint assigned to your smart home skill. You can find this URL listed as the Redirect URL on the Configuration page for your app on the developer portal. Also, the OAuth provider must have a certificate signed by an Amazon-approved certificate authority. For a list of approved certificate authorities, see https://wiki.mozilla.org/CA:IncludedCAs.

To learn more about how authentication in Alexa works, see Linking an Alexa User with a User in Your System. To learn more about the scope object, see scope

Request/Response Messages

Alexa sends your skill directive messages that request something on behalf of the customer. You respond with an Alexa.Response or an error message that is relevant to the request and why it failed.

Directive and Event Format

Directives sent to your skill and events sent by your skill back to the Alexa, share the same basic structure. Directive and events contain the following top-level objects:

In addition, events 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": {
  "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
  "namespace": "Alexa.PowerController",
  "name": "TurnOn",
  "payloadVersion": "3"
}

A header can contain the following properties:

Property Description

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.
name The name of the directive such as TurnOn or TurnOff
namespace A string that specifies the category for the message payload. This aligns to the interface that contains that directive. For example:
  • Alexa.PowerController
  • Alexa.ChannelController
payloadVersion The API version that should be applied to the payload message. The version covered in this, and related documents, is 3. Version 2 describes the currently released version of the Smart Home Skill API.

Endpoint object

An endpoint object identifies the device to communicate with. In addition, the endpoint contains an authentication token to enable the communication with the device. Currently endpoints are included in directives but not in event responses.

Following is an example JSON for a typical message endpoint:

 "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-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

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

endpointId

A device identifier. The identifier must be unique across all devices owned by an end user within the domain for 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 types supported.

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

Context object

Use the Context object to report state in any event message. A context contains an array of property objects and their state according to one of the property schemas 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 information about the structure of properties, see Property Schemas.

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


"context": {
    "properties": [ {
      "namespace": "Alexa.PowerController",
      "name": "powerState",
      "value": "ON",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  }
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 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 Object

The payload contents for a message varies depending on the interface that defines the directive.

Discovery Directives and Events

The first step for a smart home skill is to enable discovery of customer devices and report the capabilities that the skill can control for the devices. See Alexa.Discovery for more details.

Other Directives and Events

The payload for a directive or event depends on the name of the directive specified in the header. Payload directive and event contents are described in detail in each capability interface topic.

Operation Capability Interface
Turn things 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
Indicate an error has occurred Alexa.ErrorResponse