---
metadata:
- name: generator
content: Diplodoc Platform v5.48.2
alternate:
- https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/toggle.md
- https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/toggle.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/dialogs/smart-home/doc/en/llms.txt
# Toggle
`devices.capabilities.toggle`
Control of device parameters that can only be in one of two states. For example, buttons, toggles, and similar controls that enable or disable an additional function of the device.
## Common voice commands {#voice-scenario}
1. _Алиса, включи ионизатор на увлажнителе._
Translation: Alice, turn on the ionizer on the humidifier.
1. _Алиса, выключи звук на телеке._
Translation: Alice, mute sound on the TV.
1. _Алиса, включи подсветку чайника._
Translation: Alice, turn on the teapot backlight.
## Capability description {#discovery}
The structure is used in the response to the [Information about user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/get-devices.md) operation.
#### Capability parameters {#discovery-parameters}
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
type
|
[String](*string)
|
Capability type.
|
Yes
||
||
retrievable
|
[Boolean](*boolean)
|
If it's possible to request the state of this device capability. Acceptable values:
- `true`: A state request is available for the capability. Default value.
- `false`: A state request is not available for the capability.
|
No
||
||
reportable
|
[Boolean](*boolean)
|
Indicates that the [notification service](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference-alerts/post-skill_id-callback-state.md) reports the capability state change. Acceptable values:
- `true`: Notification is enabled. The manufacturer notifies Yandex Smart Home of every change in the capability state.
- `false`: Notification is disabled. The manufacturer doesn't notify Yandex Smart Home of the capability state change. Default value.
|
No
||
||
parameters
|
[Object](*object)
|
`parameters` object.
|
Yes
||
|#
**`parameters` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
instance
|
[String](*string)
|
Function name for this capability. You can find the acceptable values in the [List of functions](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/toggle-instance.md) section.
|
Yes
||
|#
#### Example of use {#discovery-example}
Yandex Smart Home requests the details of user devices from the provider. The provider responds that the user has a humidifier with an ionizer.
{% list tabs %}
- Request
```bash translate=no
curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'
```
- Response
```json translate=no
HTTP/1.1 200 OK
{
"request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"user_id": "user-001",
"devices": [
{
"id": "humidifier-001-xdh",
"name": "увлажнитель",
"description": "умный увлажнитель xdh",
"room": "спальня",
"type": "devices.types.humidifier",
"custom_data": {
"api_location": "rus"
},
"capabilities": [
{
"type": "devices.capabilities.toggle"
"retrievable": true,
"reportable": false,
"parameters": {
"instance": "ionization"
}
}
],
"device_info": {
"manufacturer": "Provider-01",
"model": "xdh 1",
"hw_version": "1.2",
"sw_version": "5.4"
}
}
]
}
}
```
{% endlist %}
## Current capability state {#state}
The structure is used in the response to the [Information about the states of user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query.md) operation and in the request body of the [Notification about device state change](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference-alerts/post-skill_id-callback-state.md) operation.
#### Capability parameters {#state-parameters}
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
type
|
[String](*string)
|
Capability type.
|
Yes
||
||
state
|
[Object](*object)
|
Capability state parameters.
|
Yes
||
|#
**`state` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
instance
|
[String](*string)
|
Function name for this capability. You can find the acceptable values in the [List of functions](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/toggle-instance.md) section.
|
Yes
||
||
value
|
[Boolean](*boolean)
|
Function value for this capability. Acceptable values:
- `true`: The function is enabled.
- `false`: The function is disabled.
|
Yes
||
|#
#### Example of use {#state-example}
Yandex Smart Home requests the provider to change the state of the user device. The provider responds with the state of the user device.
{% list tabs %}
- Request
```bash translate=no
curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json' \
-d '{
"devices":
[
{
"id": "humidifier-001-xdh",
"custom_data": {
"api_location": "rus"
}
}
]
}'
```
- Response
```json translate=no
HTTP/1.1 200 OK
{
"request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"devices": [
{
"id": "humidifier-001-xdh",
"capabilities": [
{
"type": "devices.capabilities.toggle",
"state": {
"instance": "ionization",
"value": true
}
}
]
}
]
}
}
```
{% endlist %}
## Change the state of the device capability {#action}
The structure is used in the response to the [Change device state](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-action.md) operation.
#### Capability parameters {#action-parameters}
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
type
|
[String](*string)
|
Capability type.
|
Yes
||
||
state
|
[Object](*object)
|
An object that describes the result of changing the state of the capability.
|
Yes
||
|#
**`state` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
instance
|
[String](*string)
|
Function name for this capability. You can find the acceptable values in the [List of functions](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/toggle-instance.md) section.
|
Yes
||
||
action_result
|
[Object](*object)
|
Result of changing the state of the device capability.
|
No
||
|#
**`action_result` object**
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||
||
status
|
[String](*string)
|
Status of the device capability state change. Acceptable values:
- `DONE`: The state of the device capability state changed.
- `ERROR`: An error occurred when changing the state of the device capability.
|
Yes
||
||
error_code
|
[String](*string)
|
An error code from the list of [errors](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/response-codes.md). If `status:"ERROR"`, the parameter is required.
|
No
||
||
error_message
|
[String](*string)
|
Extended human-readable description of a possible error. It is displayed only in the [Testing section](https://yandex.ru/dev/dialogs/smart-home/doc/en/testing.md) of the [developer console](https://dialogs.yandex.ru/developer/).
|
No
||
|#
#### Example of use {#action-example}
Yandex Smart Home requests the provider to change the state of the user's devices. The provider responds with the result of user device state change.
{% list tabs %}
- Request
```bash translate=no
curl -i -X POST 'https://endpoint_url/v1.0/user/devices/action' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json' \
-d '{
"payload": {
"devices": [{
"id": "humidifier-001-xdh",
"custom_data": {
"api_location": "rus"
},
"capabilities": [{
"type": "devices.capabilities.toggle",
"state": {
"instance": "ionization",
"value": false
}
}]
}]
}
}'
```
- Response
```json translate=no
HTTP/1.1 200 OK
{
"request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
"payload": {
"devices": [
{
"id": "humidifier-001-xdh",
"capabilities": [
{
"type": "devices.capabilities.toggle",
"state": {
"instance": "ionization",
"action_result": {
"status": "DONE"
}
}
}
]
}
]
}
}
```
{% endlist %}
[*object]:
List of `"key": value` pairs separated by commas. The list is enclosed in curly brackets `{}`.
```json translate=no
{
"name": "John",
"surname": "Smith"
}
```
[*string]:
String enclosed in quotation marks, for example: `"Hello, world"`.
[*boolean]:
Boolean value without quotes: `true` or `false`.