Change device state

Changes the current state of user devices.

Example situation when the current request is sent: the user opens the  Yango Play app and wants to change the state of their devices.

In response to this request, the provider changes the state of the requested user devices.

  1. Smart home platform request format
  2. Provider response format
  3. Example

Smart home platform request format

Yango Smart Home sends a request to the provider's Endpoint URL (https://example.com/).

POST https://example.com/v1.0/user/devices/action

Request headers

Header Description Required
Authorization User's authorization token. Yes
Content-Type The format of sent/submitted data. Possible values: application/json. Yes, in operations with HTTP POST
X-Request-Id Request ID. Must be logged on the provider's side for investigating incidents and problems. Yes
Header Description Required
Authorization User's authorization token. Yes
Content-Type The format of sent/submitted data. Possible values: application/json. Yes, in operations with HTTP POST
X-Request-Id Request ID. Must be logged on the provider's side for investigating incidents and problems. Yes

Request body format

{
  "payload": {
    "devices":[
      {
        "id": String,
        "custom_data": Object,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ]
      }
    ]  
  }
}
Parameter Type Description Required
payload Object Object with devices. Yes
payload object
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
custom_data Object An object with the device that the provider sent in response to the Information about user devices request. Consists of a set of "key":"value" pairs with any nesting level, providing additional information about the device. Object content size must not exceed 1024 bytes. No
capabilities Array of objects Array with information about device capabilities. Yes
capabilities object
<capability1> Object Capability and command to change it. For more information about the list of available capabilities and their parameters, see About capabilities. Yes
<capability2> Object Capability and command to change it. For more information about the list of available capabilities and their parameters, see About capabilities. Yes
Parameter Type Description Required
payload Object Object with devices. Yes
payload object
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
custom_data Object An object with the device that the provider sent in response to the Information about user devices request. Consists of a set of "key":"value" pairs with any nesting level, providing additional information about the device. Object content size must not exceed 1024 bytes. No
capabilities Array of objects Array with information about device capabilities. Yes
capabilities object
<capability1> Object Capability and command to change it. For more information about the list of available capabilities and their parameters, see About capabilities. Yes
<capability2> Object Capability and command to change it. For more information about the list of available capabilities and their parameters, see About capabilities. Yes

Provider response format

The provider must use the correct format to respond to the request received from Yango Smart Home.

HTTP/1.1 200 OK

{
    "request_id": String,
    "payload": {
      "devices": [
        {
          "id": String,
          "capabilities": [
            "<capability1>": Object,
            "<capability2>": Object,
            ...
          ],
          "action_result": {
            "status": String,
            "error_code": String,
            "error_message": String
          }
        },
        ...
      ]
    }
}
Parameter Type Description Required
request_id String Request ID. Yes
payload Object Object with devices. Yes
payload object
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
capabilities Array of objects Array with information about device capabilities. Yes, if the action_result parameter is omitted
action_result Object

Result of device state change. This parameter is required if capabilities is missing.

Note.

We recommend that you return a parameter for each capability separately. If this is not possible, return the result for the entire device.

The response to the request is considered successful (status:"DONE") if at least one state of the device has changed.

 Yes, if the capabilities parameter is omitted
capabilities object
<capability1> Object Command result. For more information about the list of available capabilities and their parameters, see About capabilities. No
<capability2> Object Command result. For more information about the list of available capabilities and their parameters, see About capabilities. No
action_result object
status String

Status of the device state change. Acceptable values:

  • DONE: device state changed.
  • ERROR: an error occurred when changing the device state.
 No
error_code String An error code from the list. If the field is filled in, the capabilities and properties parameters are ignored. No
error_message String Extended human-readable description of a possible error. Available only on the Testing tab of the developer console. No
Parameter Type Description Required
request_id String Request ID. Yes
payload Object Object with devices. Yes
payload object
devices Array of objects Array of the user's devices. Yes
devices object
id String Device ID. It must be unique among all the manufacturer's devices. Yes
capabilities Array of objects Array with information about device capabilities. Yes, if the action_result parameter is omitted
action_result Object

Result of device state change. This parameter is required if capabilities is missing.

Note.

We recommend that you return a parameter for each capability separately. If this is not possible, return the result for the entire device.

The response to the request is considered successful (status:"DONE") if at least one state of the device has changed.

 Yes, if the capabilities parameter is omitted
capabilities object
<capability1> Object Command result. For more information about the list of available capabilities and their parameters, see About capabilities. No
<capability2> Object Command result. For more information about the list of available capabilities and their parameters, see About capabilities. No
action_result object
status String

Status of the device state change. Acceptable values:

  • DONE: device state changed.
  • ERROR: an error occurred when changing the device state.
 No
error_code String An error code from the list. If the field is filled in, the capabilities and properties parameters are ignored. No
error_message String Extended human-readable description of a possible error. Available only on the Testing tab of the developer console. No

Codes associated with the request

Example

curl -i -X POST 'https://example.com/v1.0/user/devices/action' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'

Request body

{
    "payload": {
        "devices": [{
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            },
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "hsv",
                    "value": {
                        "h": 255,
                        "s": 50,
                        "v": 100
                    }
                }
            },
            {
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": false
                }
            }]
        }, {
            "id": "sock-56GF-3",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": false
                }
            }]
        }]
    }
}