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 the developer guide.

Request format

{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
  • requestId: String. Required. ID of request.
  • inputs:
    • intent: String. Required. action.devices.SYNC
    • (No payload)

Response format

{
  "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"
        }
      }
    ]
  }
}
  • requestId: String. Required. ID of request.
  • payload:
    • errorCode: String. Optional. For systematic errors on SYNC. See the error codes documentation for the valid values you can set.
    • debugString: String. Optional. Detailed error which will never be presented to users but may be logged or used during development.
    • agentUserId: String (up to 256 bytes). 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).
    • devices: Array<Object>. Array of devices. Zero or more devices are returned (zero devices meaning the user has no devices, or has disconnected them all). Each device has the following properties:
      • id: String. Required. The ID of the device in the partner's cloud. This must be unique for the user and for the partner, 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 (for example, action.devices.types.LIGHT). See the full list of device types.
      • traits: Array<String>. Required. List of traits this device supports (for example, action.devices.traits.OnOff). This defines the commands, attributes, and states that the device has. See the full list of device traits.
      • name: Object. Required. Names of this device.
        • defaultNames: Array<String>. Optional. List of names provided by the partner rather than the user, often manufacturer names, SKUs, etc.
        • 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<String>. Optional. Additional names provided by the user for the device.
      • willReportState: Boolean. Required. Indicates whether this device supports updating state asynchronously via Report State.
      • roomHint: String. Optional. Provides the current room of the device in the user's home to simplify setup.
      • deviceInfo: Object. Optional. 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 partner 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. Optional, aligned with per-trait attributes as in Attributes below. Right-hand values are string | int | boolean | number.
      • customData: Object. Optional; this is a special object defined by the partner which will be attached to future QUERY and EXECUTE requests. Partners can use this object to store additional information about the device to improve performance or routing within their cloud, such as the global region of the device. Data in this object has a few constraints:
        • No Personally Identifiable Information.
        • Data should change rarely, akin to other attributes -- so this should not contain real-time state.
        • The total object is limited to 512 bytes per device.
      • otherDeviceIds: Array<Object>. Optional. List of objects that contain alternate IDs used to identify a cloud synced device for local execution. Each object has the following properties:
        • agentId: String. Optional. The agent's ID. Generally, this is the project ID in the Actions console.
        • deviceId: String. Device ID defined by the agent. The device ID must be unique.