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 Query and execute.

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.QUERY")

Intent request type.
payload Object

Required.

QUERY request payload.
devices Array

Required.

List of target devices.
[item, ...] Object

Device targets to query.
id String

Required.

Device ID, as per the ID provided in SYNC.
customData Object

If the opaque customData object is provided in SYNC, it's sent here.
Examples

QUERY intent request

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Response format

Fields Type Description
requestId String

Required.

ID of the corresponding request.
payload Object

Required.

Intent response payload.
errorCode String

An error code for the entire transaction for auth failures and developer system unavailability. For individual device errors use the errorCode within the device object.
debugString String

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

Required.

Map of devices. Maps developer device ID to object of state properties.
<string> Object

Device state.
online Boolean

Required.

Indicates if the device is online (that is, reachable) or not.
status String

Required.

Result of the query operation.

Supported values:

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.
ERROR
Unable to query the target device.
errorCode String

Expanding ERROR state if needed from the preset error codes, which will map to the errors presented to users.
Examples

QUERY intent response

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "status": "SUCCESS"
      },
      "456": {
        "on": true,
        "online": true,
        "status": "SUCCESS",
        "brightness": 80,
        "color": {
          "spectrumRgb": 16711935
        }
      }
    }
  }
}