# Smart Home Toggles Trait Schema

`action.devices.traits.Toggles` - This trait belongs to any devices with settings that can only exist in one of two states.

These settings can represent a physical button with an on/off or active/inactive
state, a checkbox in HTML, or any other sort of specifically enabled/disabled
element. If the setting has more than two states, or has a state in which
neither of the binary options is selected, it is better represented as a
[Modes](https://developers.home.google.com/cloud-to-cloud/traits/modes) trait, which equates to multi-state dials,
radio buttons (physical or HTML), or binary states that are not explicitly
on/off (for example, "AM/FM" or "hot/cold").

This trait covers one or more individual toggles which users can set. In
general, these toggles should be used for functionality that is unlinked
from other device behavior. Linked behavior, such as turning the device itself
on or off, should use more specific traits (for example, the `thermostatMode`
in the trait [TemperatureSetting](https://developers.home.google.com/cloud-to-cloud/traits/temperaturesetting)).

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| Attributes | Type | Description |
|---|---|---|
| `availableToggles` | *Array* | **Required.** List of available toggles. |
| `[*item, ...*]` | *Object* | Available toggle. |
| `name` | *String* | **Required.** Internal name of the toggle, which will be used in commands and states. This can be non-user-friendly, and will be shared across all languages. |
| `name_values` | *Array* | **Required.** Synonyms of the toggle in each supported languages. |
| `[*item, ...*]` | *Object* | Synonyms of the toggle in a given language. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `name_synonym` | *Array* | **Required.** Synonyms of the toggle. The first string in this list is used as the canonical name of the level in that language. |
| `[*item, ...*]` | *String* | Synonym name. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `lang` | *String* | **Required.** Language code (ISO 639-1). See [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages). |
| `commandOnlyToggles` | *Boolean* | (Default: `false`) Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait. |
| `queryOnlyToggles` | *Boolean* | (Default: `false`) Required if the device supports query-only execution. This attribute indicates if the device can only be queried for state information, and cannot be controlled. |

#### Examples

*Device with multiple toggle.*

```
{
  "availableToggles": [
    {
      "name": "sterilization_toggle",
      "name_values": [
        {
          "name_synonym": [
            "Clean",
            "Bio clean"
          ],
          "lang": "en"
        }
      ]
    },
    {
      "name": "energysaving_toggle",
      "name_values": [
        {
          "name_synonym": [
            "Energy saving",
            "Eco"
          ],
          "lang": "en"
        }
      ]
    }
  ]
}
```

*Device with command-only toggles.*

```
{
  "availableToggles": [
    {
      "name": "filter_toggle",
      "name_values": [
        {
          "name_synonym": [
            "Filtered",
            "Filter"
          ],
          "lang": "en"
        }
      ]
    }
  ],
  "commandOnlyToggles": true
}
```

*Device with query-only toggles.*

```
{
  "availableToggles": [
    {
      "name": "filter_toggle",
      "name_values": [
        {
          "name_synonym": [
            "Filtered",
            "Filter"
          ],
          "lang": "en"
        }
      ]
    }
  ],
  "queryOnlyToggles": true
}
```

## Device STATES

Entities with this trait may report the following
states as part of the [`QUERY`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| States | Type | Description |
|---|---|---|
| `currentToggleSettings` | *Object* | **Required.** Key/value pair with the toggle `name` of the device as the key, and the current state as the value. |
| `<string>` | *Boolean* | Current toggle state. |

#### Examples

*Is sterilization on?*

```
{
  "currentToggleSettings": {
    "sterilization_toggle": true,
    "energysaving_toggle": false
  }
}
```

## Device COMMANDS

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `action.devices.commands.SetToggles`

Set a given toggle state.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `updateToggleSettings` | *Object* | **Required.** Key/value pair with the toggle `name` of the device as the key, and the new state as the value. |
| `<string>` | *Boolean* | New toggle state |

#### Examples

*Turn on energy saving.*

```
{
  "command": "action.devices.commands.SetToggles",
  "params": {
    "updateToggleSettings": {
      "energysaving_toggle": true
    }
  }
}
```

*Turn off filter.*

```
{
  "command": "action.devices.commands.SetToggles",
  "params": {
    "updateToggleSettings": {
      "filter_toggle": false
    }
  }
}
```

## Sample utterances

> [!NOTE]
> This is a sample of the utterances supported by this device trait, make sure to also review other [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages).

### de-DE

- Bitte schalte *Power Cool* *am Kühlschrank* aus
- stelle *den Kühlschrank* auf *Power Cool*

### en-US

- activate *power freeze* for *the freezer*
- cancel *power cool* for *the kitchen fridge*

### es-ES

- pon el *enfriamiento rápido* en *la nevera*
- quita el *enfriamiento rápido*

### fr-FR

- mets le mode *power cool* sur *le réfrigérateur*
- Éteins le mode *power freeze* du *réfrigérateur* .

### hi-IN

- *रेफ़्रिजरेटर* का *पावर कूल* मोड बंद कर दो
- *रेफ़्रिजरेटर* में *पावर कूल* मोड चालू करो

### it-IT

- disattiva il *power freeze* *del freezer*
- imposta la funzione *power freeze* *del surgelatore*

### ja-JP

- *冷蔵庫* の *急速冷凍* つけて
- *冷蔵庫* の *急速冷凍* を切ってくれる

### ko-KR

- *냉장고* *급속 냉장* 해제해
- *냉장고* 모드 *급속 냉장* 으로 바꿔

### nl-NL

- Zet *de power cool* uit op *de koelkast*
- zet *de koelkast* op *superkoelen*

### pt-BR

- Ativa a função *power freeze* no *congelador* .
- Desativa o *bloqueio infantil* do *forno* .
- desligar o *power cool* da *geladeira*
- iniciar o modo *power freeze* do *freezer*

### sv-SE

- Stäng av *power cool* i *kylskåpet*
- sätt på *power freeze* på *frysen*

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).