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 Yango and provider accounts are linked.
  • The user opened the  Yango Play → Plus → Smart home device and tapped Update next to the manufacturer's name.
Note.

This request is also sent after the Yango 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, Yango Smart Home leaves such devices unchanged. Only the user can delete a device from the list.

  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/).

GET https://example.com/v1.0/user/devices

Request headers

Header Description Required
Authorization User's authorization token. Yes
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
X-Request-Id Request ID. Must be logged on the provider's side for investigating incidents and problems. Yes

Provider response format

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

{
  "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
user_id String User ID. Yes
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
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 About devices. 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. Yango Smart Home saves this object and sends it in Information about the states of the user's devices and Changing the state of devices requests. 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's properties. Yes, if the capabilities parameter is omitted
device_info Object Additional technical information about the device. To find this information, on the  Yango Play app home screen, choose a device, click Settings in the upper right corner, and choose About the device. This data helps you quickly identify the device when the user contacts Yango support or manufacturer's support. Yes, for official skills
capabilities object
<capability1> Object Description of capability. For more information about the list of available capabilities and their parameters, see About capabilities. No
<capability2> Object Description of capability. For more information about the list of available capabilities and their parameters, see About capabilities. No
properties object
<property1> Object Description of a property. For a more detailed list of available properties and their parameters, see About properties. No
<property2> Object Description of a property. For a more detailed list of available properties and their parameters, see About properties. No
device_info object
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
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
Parameter Type Description Required
request_id String Request ID. Yes
payload Object Object with devices. Yes
payload object
user_id String User ID. Yes
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
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 About devices. 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. Yango Smart Home saves this object and sends it in Information about the states of the user's devices and Changing the state of devices requests. 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's properties. Yes, if the capabilities parameter is omitted
device_info Object Additional technical information about the device. To find this information, on the  Yango Play app home screen, choose a device, click Settings in the upper right corner, and choose About the device. This data helps you quickly identify the device when the user contacts Yango support or manufacturer's support. Yes, for official skills
capabilities object
<capability1> Object Description of capability. For more information about the list of available capabilities and their parameters, see About capabilities. No
<capability2> Object Description of capability. For more information about the list of available capabilities and their parameters, see About capabilities. No
properties object
<property1> Object Description of a property. For a more detailed list of available properties and their parameters, see About properties. No
<property2> Object Description of a property. For a more detailed list of available properties and their parameters, see About properties. No
device_info object
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
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

Example

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

curl -i -X GET 'https://example.com/v1.0/user/devices' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...'