action.devices.QUERY

This intent queries your fulfillment for the current states of devices, including whether the device is online and reachable. Your QUERY response should return only state information. Updating the attributes and traits of the device is handled by the SYNC response.

For more details, see the developer guide.

Request format

{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "foo"
          }
        }, {
          "id": "456",
          "customData": {
            "fooValue": 12,
            "barValue": false,
            "bazValue": "bar"
          }
        }]
      }
    }]
}
  • requestId: String. Required. ID of request.
  • inputs:
    • intent: String. Required. action.devices.QUERY
    • payload: Object. Required
      • devices: Array<Object>. Required.
        • id: Required. Partner ID to query, as per the id provided in SYNC.
        • customData: Optional. If the opaque customData object is provided in SYNC, it's sent here.

Response format

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true
      },
      "456": {
        "on": true,
        "online": true,
        "brightness": 80,
        "color": {
          "name": "cerulean",
          "spectrumRGB": 31655
        }
      }
    }
  }
}
  • requestId: String. Required. ID of request.
  • payload:
    • errorCode: String. Optional. An error code for the entire transaction—for auth failures and partner system unavailability. For individual device errors use the errorCode within the device object.
    • debugString: String. Optional. Detailed error which will never be presented to users but may be logged or used during development.
    • devices: Object. Map of devices. Each property has the following name and value:
      • id: Object. Required. Maps partner device ID to object of state properties, as defined in States section below.
        • online: Boolean. Required. Indicates if the device is online (that is, reachable) or not.
        • errorCode: String. Optional. Expanding ERROR state if needed from the preset error codes, which will map to the errors presented to users. See the error codes documentation for the valid values you can set.
        • status: String. Required. The valid status types include:
          • SUCCESS: Confirm that the query succeeded.
          • OFFLINE: Target device is in offline state or unreachable.
          • EXCEPTIONS: There is an issue or alert associated with a query. The query could succeed or fail. This status type is typically set when you want to send additional information about another connected device, as shown in this example. See the exception codes documentation for a list of the valid values you can set.
          • ERROR: Unable to query the target device.
        • debugString: String. Optional. Detailed error which will never be presented to users but may be logged or used during development.