Alexa.ColorTemperatureController

The Alexa.ColorTemperatureController interface describes the messages used to control and report the color temperature of a endpoint that supports tunable white light.

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.

DecreaseColorTemperature

A request to lower the Kelvin temperature value of the device. This directive does not specify a specific setting, but asks for a warmer setting relative to the current device setting. You can choose how much to adjust the setting of the specified device depending on its current setting, capabilities and other values. If the device cannot be decreased further, set it to its minimum color temperature.

“Alexa, set the device name warmer/softer”

“Alexa, set the dining room softer”

“Alexa, make the living room warmer”

Example Request:


{
    "directive": {
        "header": {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "DecreaseColorTemperature",
            "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": {}
    }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

IncreaseColorTemperature

A request to raise the Kelvin temperature value of the device. This directive does not specify a specific setting, but asks for a cooler/whiter setting relative to the current device setting. You can choose how much to adjust the setting of the specified device depending on its current setting, capabilities and other values. If the device cannot be incremented further, set it to its maximum color temperature.

“Alexa, set the device name cooler/whiter”

“Alexa, set the dining room cooler”

“Alexa, make the living room light whiter”

Example Request:


{
    "directive": {
        "header": {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "IncreaseColorTemperature",
            "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": {}
    }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

SetColorTemperature

Request to change the color temperature of the specified device change to a specified setting. The following table lists some possible color temperature requests and related values that the API would send. If your lighting device does not support the requested value, its recommended that you set your device to the nearest possible value.

Shades of White colorTemperatureInKelvin value
warm, warm white 2200
incandescent, soft white 2700
white 4000
daylight, daylight white 5500
cool, cool white 7000

“Alexa, change the device name to shade of white”

“Alexa, make the living room warm white”

“Alexa, set the kitchen to daylight”

“Alexa, schalte Schlafzimmerlicht auf warmes Weiß”

Example Request


{
    "directive": {
        "header": {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "SetColorTemperature",
            "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": {
            "colorTemperatureInKelvin": 7500
        }
    }
}

Payload details

Field Description Type Required
[colorTemperatureinKelvin][property-schemas#colortemperatureinkelvin] An integer that indicates the requested color temperature in Kelvin degrees. Valid range is 1000 to 10000, inclusive integer 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
colorTemperatureInKelvin [colorTemperatureinKelvin][property-schemas#colortemperatureinkelvin] Indicates the requested color temperature in Kelvin degrees. The value is an integer ranging from 1000 to 10000, inclusive.

Response

Send an Response event when successfully responding to a request for a change in color temperature. You should include the state of reportable properties in the context of the message.

Response example

The following example shows a response for a endpoint that supports tunable white light.

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

If the device is in a mode in which it cannot be controlled with a color temperature directive, return a NOT_SUPPORTED_IN_CURRENT_MODE error. For example, return this error to indicate that an IncreaseColorTemperature or DecreaseColorTemperature request was made to a light that is currently set to an HSB color. In this scenario, Alexa responds, “That only works when your light is set to a shade of white.”

NOT_SUPPORTED_IN_CURRENT_MODE example

{
  "event": {
    "header": {
      "namespace": "Alexa.ColorTemperatureController",
      "name": "ErrorResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "type": "NOT_SUPPORTED_IN_CURRENT_MODE",
      "message": "The light is currently set to a color.",
      "currentDeviceMode": "COLOR"
      }
  }
}

Payload details

Field Description Type Required
currentDeviceMode Indicates the current device mode that prevents the setting change. string. Valid values are AUTO, AWAY, COLOR, COOL, HEAT, OTHER. yes

Additional Sample Code

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

ColorTemperatureController

Interface Description
Alexa.BrightnessController Controls the brightness of an endpoint.
Alexa.ColorController Sets the color of a light endpoint.