Your Alexa Dashboards Settings

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

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

  • English - all locales
  • German
  • Japanese

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.

User: Alexa, set the device name warmer/softer

User: Alexa, set the dining room softer

User: 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": "access-token-from-skill"
            },
            "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.

User: Alexa, set the device name cooler/whiter

User: Alexa, set the dining room cooler

User: 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": "access-token-from-skill"
            },
            "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

User: Alexa, change the device name to shade of white

User: Alexa, make the living room warm white

User: Alexa, set the kitchen to daylight

User: 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": "access-token-from-skill"
            },
            "endpointId": "appliance-001",
            "cookie": {}
        },
        "payload": {
            "colorTemperatureInKelvin": 7500
        }
    }
}

Payload details

Field Description Type Required
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 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 reportable 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.

Reportable Properties

Property Name Type Description
colorTemperatureInKelvin colorTemperatureinKelvin 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.

{
    "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": "access-token-from-Amazon"
            },
            "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": "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 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.