感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Alexa.ColorController Interface

The Alexa.ColorController interface describes the messages used to change and report the color of an endpoint such as a color-changing light bulb.

For the list of locales that are supported for the ColorController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.ColorController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, set the front porch light to blue.
Alexa, set the bedroom light to red.
Alexa, change the kitchen to the color blue.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Directives

SetColor

Request to set the color of the light for an endpoint.

User: Alexa, set the device name to color

User: Alexa, set the bedroom light to red

User: Alexa, change the kitchen to the color blue

User: setze Wohnzimmerlicht auf rosa

Example Request:

{
    "directive": {
        "header": {
            "namespace": "Alexa.ColorController",
            "name": "SetColor",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "appliance-001",
            "cookie": {}
        },
        "payload": {
            "color": {
                "hue": 350.5,
                "saturation": 0.7138,
                "brightness": 0.6524
            }
        }
    }
}

Payload details

Field Description Type Required
color Describes the color to set for the light. Specified in the hue, saturation, brightness (HSB) color model. color object Yes

Properties and Events

For this capability, you must either reply:

  • Synchronously, which means you send a Response event to Alexa from the Lambda function.
  • Asynchronously, which means you send a Response event to the Alexa event gateway. When you reply asynchronously, you must include a scope with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.

When you send a Response, you should include the state of the interface properties in the context of the message.

For lighting endpoints that support the ColorController and ColorTemperatureController interfaces, report the state of color when an endpoint is set to a color, and report the state of colorTemperatureInKelvin when an endpoint is set to a shade of white.

Properties

Property Name Type Description
color Color Describes the color to set for the light. The value is specified in the hue, saturation, brightness (HSB) color model. Report the color property only when the bulb is set to an HSB color.

Response

If the SetColor directive was successfully handled, you should respond with an Response event and include the state of the color property in the context of the message.

Example Response

The following example shows a response for a endpoint that supports HSB colors or for a endpoint that supports HSB colors and color temperature, but is currently set to an HSB color.

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorController",
            "name": "color",
            "value": {
                "hue": 350.5,
                "saturation": 0.7138,
                "brightness": 0.6524
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 1000
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
              "type": "BearerToken",
              "token": "access-token-from-Amazon"
      },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

ColorController

Interface Description
Alexa.ColorTemperatureController Sets the color temperature of a tunable light endpoint.