Method: devices.sync

Gets all the devices associated with the given third-party user. The third-party user's identity is passed in as agentUserId. The agent is identified by the JWT signed by the third-party partner's service account.

HTTP request

POST https://homegraph.googleapis.com/v1/devices:sync

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestId": string,
  "agentUserId": string
}
Fields
requestId

string

Request ID used for debugging.

agentUserId

string

Required. Third-party user ID.

Response body

If successful, the response body contains data with the following structure:

Response type for the devices.sync call. This should follow the same format as the Actions on Google action.devices.SYNC response.

Example
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [{
      "id": "123",
      "type": "action.devices.types.OUTLET",
      "traits": [
        "action.devices.traits.OnOff"
      ],
      "name": {
        "defaultNames": ["My Outlet 1234"],
        "name": "Night light",
        "nicknames": ["wall plug"]
      },
      "willReportState": false,
      "deviceInfo": {
        "manufacturer": "lights-out-inc",
        "model": "hs1234",
        "hwVersion": "3.2",
        "swVersion": "11.4"
      },
      "customData": {
        "fooValue": 74,
        "barValue": true,
        "bazValue": "foo"
      }
    }]
  }
}
JSON representation 
{
  "requestId": string,
  "payload": {
    object (SyncResponsePayload)
  }
}
Fields
requestId

string

Request ID used for debugging. Copied from the request.

payload

object (SyncResponsePayload)

Devices associated with the third-party user.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/homegraph

For more information, see the OAuth 2.0 Overview.

SyncResponsePayload

Payload containing device information.

JSON representation 
{
  "agentUserId": string,
  "devices": [
    {
      object (Device)
    }
  ]
}
Fields
agentUserId

string

Third-party user ID

devices[]

object (Device)

Devices associated with the third-party user.

Device

Third-party partner's device definition.

JSON representation 
{
  "id": string,
  "type": string,
  "traits": [
    string
  ],
  "name": {
    object (DeviceNames)
  },
  "willReportState": boolean,
  "roomHint": string,
  "structureHint": string,
  "deviceInfo": {
    object (DeviceInfo)
  },
  "attributes": {
    object
  },
  "customData": string,
  "otherDeviceIds": [
    {
      object (AgentOtherDeviceId)
    }
  ]
}
Fields
id

string

Third-party partner's device ID.

type

string

Hardware type of the device (e.g. light, outlet, etc).

traits[]

string

Traits supported by the device.

name

object (DeviceNames)

Name of the device given by the third party. This includes names given to the device via third party device manufacturer's app, model names for the device, etc.

willReportState

boolean

Indicates whether the state of this device is being reported to Google through devices.reportStateAndNotification call.

roomHint

string

If the third-party partner's cloud configuration includes placing devices in rooms, the name of the room can be provided here.

structureHint

string

As in roomHint, for structures that users set up in the partner's system.

deviceInfo

object (DeviceInfo)

Device manufacturer, model, hardware version, and software version.

attributes

object (Struct format)

Attributes for the traits supported by the device.

customData

string

Custom JSON data provided by the manufacturer and attached to QUERY and EXECUTE requests in AoG.

otherDeviceIds[]

object (AgentOtherDeviceId)

IDs of other devices associated with this device. This is used to represent a device group (e.g. bonded zone) or "facets" synced through different flows (e.g. Google Nest Hub Max with a Nest Camera).

This may also be used to pass in alternate IDs used to identify a cloud synced device for local execution (i.e. local verification). If used for local verification, this field is synced from the cloud.

DeviceNames

Different names for the device.

JSON representation 
{
  "name": string,
  "nicknames": [
    string
  ],
  "defaultNames": [
    string
  ]
}
Fields
name

string

Primary name of the device, generally provided by the user.

nicknames[]

string

Additional names provided by the user for the device.

defaultNames[]

string

List of names provided by the partner rather than the user, often manufacturer names, SKUs, etc.

DeviceInfo

Device information.

JSON representation 
{
  "manufacturer": string,
  "model": string,
  "hwVersion": string,
  "swVersion": string
}
Fields
manufacturer

string

Device manufacturer.

model

string

Device model.

hwVersion

string

Device hardware version.

swVersion

string

Device software version.

AgentOtherDeviceId

Identifies a device in the third party or first party system.

JSON representation 
{
  "agentId": string,
  "deviceId": string
}
Fields
agentId

string

The agent's ID. Generally it is the agent's AoG project id.

deviceId

string

Device ID defined by the agent. The deviceId must be unique.