action.devices.SYNC

This intent requests the list of devices associated with the given user and their capabilities.

It is triggered during account linking or when a user manually resyncs their devices. Your fulfillment should respond with the supported traits and attributes for each device.

Your SYNC response should return all devices associated with the user. This does not determine whether any particular device is reachable. This is handled by the QUERY and EXECUTE responses.

For more details, see Identify and sync.

Request format

Fields Type Description
requestId String

Required.

ID of the request.
inputs Array

Required.

List of inputs matching the intent request.
[item, ...] Object

Type and payload associated with the intent request.
intent

Required.

(Constant value: "action.devices.SYNC")

Intent request type.
Examples

SYNC intent request

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}

Response format

Fields Type Description
requestId String

Required.

ID of the corresponding request.
payload Object

Required.

Intent response payload.
agentUserId String

Required.

Reflects the unique (and immutable) user ID on the agent's platform. The string is opaque to Google, so if there's an immutable form vs a mutable form on the agent side, use the immutable form (e.g. an account number rather than email).
errorCode String

For systematic errors on SYNC
debugString String

Detailed error which will never be presented to users but may be logged or used during development.
devices Array

Required.

List of devices owned by the user. Zero or more devices are returned (zero devices meaning the user has no devices, or has disconnected them all).
[item, ...] Object

Device metadata.
id String

Required.

The ID of the device in the developer's cloud. This must be unique for the user and for the developer, as in cases of sharing we may use this to dedupe multiple views of the same device. It should be immutable for the device; if it changes, the Assistant will treat it as a new device.
type String

Required.

The hardware type of device.
traits Array

Required.

List of traits this device has. This defines the commands, attributes, and states that the device supports.
[item, ...] String

Name of the supported trait.
name Object

Required.

Names of this device.
defaultNames Array

List of names provided by the developer rather than the user, often manufacturer names, SKUs, etc.
[item, ...] String

Device default name.
name String

Required.

Primary name of the device, generally provided by the user. This is also the name the Assistant will prefer to describe the device in responses.
nicknames Array

Additional names provided by the user for the device.
[item, ...] String

Device nickname.
willReportState Boolean

Required.

Indicates whether this device will have its states updated by the Real Time Feed. (true to use the Real Time Feed for reporting state, and false to use the polling model.)
notificationSupportedByAgent Boolean

(Default: false)

Indicates whether notifications are enabled for the device.
roomHint String

Provides the current room of the device in the user's home to simplify setup.
deviceInfo Object

Contains fields describing the device for use in one-off logic if needed (e.g. 'broken firmware version X of light Y requires adjusting color', or 'security flaw requires notifying all users of firmware Z').
manufacturer String

Especially useful when the developer is a hub for other devices. Google may provide a standard list of manufacturers here so that e.g. TP-Link and Smartthings both describe 'osram' the same way.
model String

The model or SKU identifier of the particular device.
hwVersion String

Specific version number attached to the hardware if available.
swVersion String

Specific version number attached to the software/firmware, if available.
attributes Object

Aligned with per-trait attributes described in each trait schema reference.
customData Object

Object defined by the developer which will be attached to future QUERY and EXECUTE requests, maximum of 512 bytes per device. Use this object to store additional information about the device your cloud service may need, such as the global region of the device. Data in this object has a few constraints: No sensitive information, including but not limited to Personally Identifiable Information.
otherDeviceIds Array

List of alternate IDs used to identify a cloud synced device for local execution.
[item, ...] Object

Alternate device ID.
agentId String

The agent's ID. Generally, this is the project ID in the Actions console.
deviceId String

Required.

Device ID defined by the agent. The device ID must be unique.
Examples

SYNC intent response

{
  "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,
        "roomHint": "kitchen",
        "deviceInfo": {
          "manufacturer": "lights-out-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id"
          }
        ],
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      },
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting"
        ],
        "name": {
          "defaultNames": [
            "lights out inc. bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": false,
        "roomHint": "office",
        "attributes": {
          "colorModel": "rgb",
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 9000
          },
          "commandOnlyColorSetting": false
        },
        "deviceInfo": {
          "manufacturer": "lights out inc.",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "bar"
        }
      }
    ]
  }
}