Change device state

Changes the current state of user devices.

Example case where this request is sent: the user opens the Home with Alice 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.

Smart home platform request format

The smart home platform 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

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

Parameter	Type	Description	Required
devices	Array of objects	Array of the user's devices.	Yes

devices object

Parameter	Type	Description	Required
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

Parameter	Type	Description	Required
<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 the smart home platform.

Response successful

Response with error

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

Parameter	Type	Description	Required
devices	Array of objects	Array of the user's devices.	Yes

devices object

Parameter	Type	Description	Required
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

Parameter	Type	Description	Required
<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

Parameter	Type	Description	Required
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

HTTP/1.1 404 Not Found

Global codes

Example

Request

Response successful

Response with error

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

HTTP/1.1 200 OK

{
  "request_id": "EE109B31-FF6C-48BD-80DB-4D07A9AFEBB3",
  "payload": {
      "devices": [{
          "id": "abc-123",
          "capabilities": [{
              "type": "devices.capabilities.color_setting",
              "state": {
                  "instance": "hsv",
                  "action_result": {
                      "status": "ERROR",
                      "error_code": "INVALID_ACTION",
                      "error_message": "the human readable error message"
                  }
              }
          },
          {
              "type": "devices.capabilities.on_off",
              "state": {
                  "instance": "on",
                  "action_result": {
                      "status": "DONE"
                  }
              }
          }]
     },
     {
        "id": "sock-56GF-3",
        "action_result": {
          "status": "ERROR",
          "error_code": "DEVICE_UNREACHABLE"
        }
     }]
  }
}

HTTP/1.1 404 Not Found

List of "key": value pairs separated by commas. The list is enclosed in curly brackets {}.

{
  "name": "John",
  "surname": "Smith"
}

An array of elements separated by a comma. As array items, you can use standard JSON elements: a string, number, true, false, object, or array. Arrays are enclosed in square brackets []:

"cities": ["Moscow", "Tokyo", "New York"]

Was the article helpful?

Information about the states of user devices

Notification of unlinked accounts