Method: devices.sync

Gets all the devices associated with the given third-party user.

The third-party user's identity is passed in via the agentUserId (see SyncRequest). This request must be authorized using service account credentials from your Actions console project.

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 Google smart home 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 device definition. Next ID = 14

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

string

Third-party device ID.
type

string

Hardware type of the device. See device types.
traits[]

string

Traits supported by the device. See device traits.
name

object (DeviceNames)

Names given to this device by your smart home Action.
willReportState

boolean

Indicates whether your smart home Action will report state of this device to Google via devices.reportStateAndNotification.
roomHint

string

Suggested name for the room where this device is installed. Google attempts to use this value during user setup.
structureHint

string

Suggested name for the structure where this device is installed. Google attempts to use this value during user setup.
deviceInfo

object (DeviceInfo)

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

object (Struct format)

Attributes for the traits supported by the device.
customData

object (Struct format)

Custom device attributes stored in Home Graph and provided to your smart home Action in each QUERY and EXECUTE intent. Data in this object has a few constraints: No sensitive information, including but not limited to Personally Identifiable Information.
otherDeviceIds[]

object (AgentOtherDeviceId)

Alternate IDs associated with this device. This is used to identify cloud synced devices enabled for local fulfillment.
notificationSupportedByAgent

boolean

Indicates whether your smart home Action will report notifications to Google for this device via devices.reportStateAndNotification.

If your smart home Action enables users to control device notifications, you should update this field and call devices.requestSync.

DeviceNames

Identifiers used to describe 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 manufacturer rather than the user, such as serial numbers, 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

Alternate third-party device ID.

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

string

Project ID for your smart home Action.
deviceId

string

Unique third-party device ID.