Information about user devices

Requests information about supported user devices.

The smart home platform sends the request to the provider on conditions that:

The user's Yandex and provider accounts are linked.
The user opens the Home with Alice app → → Устройство умного дома (Smart home device) and taps Обновить (Update) next to the manufacturer's name.

Note

This request is also sent after the Yandex and provider accounts are linked.

In response to this request, the provider must return a list of all the supported user devices with a description of the available capabilities and properties. The maximum number of user devices is 301.

If some devices are unavailable and the provider can't send information about them, Yandex Smart Home leaves such devices unchanged. Only the user can delete a device from the list.

Smart home platform request format

The smart home platform sends a request to the provider's Endpoint URL (https://example.com/).

POST https://functions.yandexcloud.net/<function_id>?integration=raw

Request body format

{
  "headers": {
    "request_id": String,
    "authorization": String
  },
  "request_type": String,
  "api_version": Float
}

Parameter	Type	Description	Required
headers	Object	Object with additional request fields.	Yes
request_type	String	Request type. Acceptable values: discovery: Information about user devices.	Yes
api_version	Float	The protocol version of Yandex Smart Home.	Yes

headers object

Parameter	Type	Description	Required
request_id	String	Request ID. Should be logged on the provider's side for investigating incidents and problems.	Yes
authorization	String	User's authorization token.	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

{
  "request_id": String,
  "payload": {
      "user_id": String,
      "devices": [
        {
          "id": String,
          "name": String,
          "description": String,
          "room": String,
          "type": String,
          "custom_data": Object,
          "capabilities": [
            "<capability1>": Object,
            "<capability2>": Object,
            ...
          ],
          "properties": [
            "<property1>": Object,
            "<property2>": Object,
            ...
          ],
          "device_info": {
            "manufacturer": String,
            "model": String,
            "hw_version": String,
            "sw_version": String
          }
        },
        ...
      ]
  }
}

Parameter	Type	Description	Required
request_id	String	Request ID.	Yes
payload	Object	Object with devices.	Yes

payload object

Parameter	Type	Description	Required
user_id	String	User ID.	Yes
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
name	String	Device name.	Yes
description	String	Device description.	No
room	String	Name of the room where the device is located.	No
type	String	Device type. See the list of device types in the Device types section.	Yes
custom_data	Object	An object consisting 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. The smart home platform will save this object and send it in requests Information about the states of user devices, Change device state.	No
capabilities	Array of objects	Array with information about device capabilities.	Yes, if the `properties` parameter is omitted
properties	Array of objects	Array with information about the device properties.	Yes, if the `capabilities` parameter is omitted
device_info	Object	Additional technical information about the device. To view this information, select the device on the Home with Alice app main screen. In the top right-hand corner, tap and choose Об устройстве (About the device). This data helps you quickly identify the device when the user contacts Yandex support or manufacturer's support.	Yes, for official skills

capabilities object

Parameter	Type	Description	Required
<capability1>	Object	Description of capability. For more information about the list of available capabilities and their parameters, see About capabilities.	No
<capability1>	Object	Description of capability. For more information about the list of available capabilities and their parameters, see About capabilities.	No

properties object

Parameter	Type	Description	Required
<property1>	Object	Property description. For more information about the list of available properties and their parameters, see About properties.	No
<property2>	Object	Property description. For more information about the list of available properties and their parameters, see About properties.	No

device_info object

Parameter	Type	Description	Required
manufacturer	String	Name of the device manufacturer. It can contain up to 256 characters. This parameter is required in the official skill description (to learn more, see About smart home).	Yes, for official skills
<property2>	Object	Property description. For more information about the list of available properties and their parameters, see About properties.	No
model	String	Name of the device model. It can contain up to 256 characters.This parameter is required in the official skill description (to learn more, see About smart home).	Yes, for official skills
hw_version	String	Device hardware version. It can contain up to 256 characters.	No
sw_version	String	Device software version. It can contain up to 256 characters.	No

For more information about returning status codes other than 200 OK, see the documentation.

HTTP/1.1 404 Not Found

Global codes

Example

This example describes the properties of a lamp featuring color control.

Request

Response successful

Response with error

curl -i POST https://functions.yandexcloud.net/<function_id>?integration=raw \
-H 'Content-Type: application/json' \
-d '{
      "headers": {
        "request_id": "1111-aaaa-2222-bbbb",
        "authorization": "Bearer 123qwe456a..."
      },
      "request_type": "discovery",
      "api_version": 1.0
}'

HTTP/1.1 200 OK

{
    "request_id": "1111-aaaa-2222-bbbb",
    "payload": {
        "user_id": "Misha-01-super-545",
        "devices": [{
                "id": "abc-123",
                "name": "лампa",
                "description": "цветная лампа",
                "room": "спальня",
                "type": "devices.types.light",
                "custom_data": {
                  "foo": 1,
                  "bar": "two",
                  "baz": false,
                  "qux": [1, "two", false],
                  "quux": {
                    "quuz": {
                      "corge": []
                    }
                  }
                },
                "capabilities": [{
                        "type": "devices.capabilities.range",
                        "retrievable": true,
                        "parameters": {
                            "instance": "brightness",
                            "unit": "unit.percent",
                            "range": {
                                "min": 0,
                                "max": 100,
                                "precision": 10
                            }
                        }
                    },
                    {
                        "type": "devices.capabilities.on_off"
                    },
                    {
                        "type": "devices.capabilities.color_setting",
                        "parameters": {
                            "color_model": "hsv",
                            "temperature_k": {
                                "min": 2700,
                                "max": 9000,
                                "precision": 1
                            }
                        }
                    }
                ],
                "device_info": {
                    "manufacturer": "Provider2",
                    "model": "hue g11",
                    "hw_version": "1.2",
                    "sw_version": "5.4"
                }
            }

        ]
    }
}

HTTP/1.1 401 Unauthorized

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?

Notification of unlinked accounts

Information about the states of user devices