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.

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.

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.

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

Indicates the requested color temperature in Kelvin degrees. The value is an integer ranging from 1000 to 10000, inclusive. Report this property only when the endpoint is set to a shade of white.

Response

If a request to set or adjust the color temperature for an endpoint was successfully handled, you should respond with an Response event and include the state of colorTemperatureInKelvin in the context of the message.

Example response

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

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":"access-token-from-Amazon"},"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 COLOR, ASLEEP, NOT_PROVISIONED, OTHER .

yes

Additional Sample Code

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