×

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.

Directives

This control and query directives in this interface are supported in skills that target the following languages:

  • English (US)
  • English (UK)
  • English (India)
  • German

See Develop Smart Home Skills in Multiple Languages for more information.

SetColor

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

“Alexa, set the device name to color”

“Alexa, set the bedroom light to red”

“Alexa, change the kitchen to the color blue”

“setze Wohnzimmerlicht auf rosa”

Example Request:

{
    "directive": {
        "header": {
            "namespace": "Alexa.ColorController",
            "name": "SetColor",
            "payloadVersion": "3",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            },
            "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 interface, you can 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 reportable properties in the context of the message.

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

Response

If the SetColor directive was successfully handled, you should respond with an Response event. You should include the state of reportable properties in the context of the message.

Example Response

{
    "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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
              "type": "BearerToken",
              "token": "Alexa-access-token"
      },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Error.Response 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.