action.devices.EXECUTE

This intent sends commands to execute on smart home devices.

Your fulfillment should process each command, transmit it to the corresponding device, and return the new state in the EXECUTE response.

A single EXECUTE intent can target multiple devices with multiple commands. For example, a triggered intent may set both brightness and color on a set of lights or may set multiple lights each to a different color.

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

Intent request type.
payload Object

Required.

EXECUTE request payload.
commands Array

Required.

List of device target and command pairs.
[item, ...] Object

Set of commands to execute on the attached device targets.
devices Array

Required.

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

Device target to execute.
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.
execution Array

Required.

List of commands to execute on target devices.
[item, ...] Object

Device command.
command String

Required.

The command to execute, usually with accompanying parameters.
params Object

Aligned with the parameters for each command.
Examples

EXECUTE intent request

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123",
                "customData": {
                  "fooValue": 74,
                  "barValue": true,
                  "bazValue": "sheepdip"
                }
              },
              {
                "id": "456",
                "customData": {
                  "fooValue": 36,
                  "barValue": false,
                  "bazValue": "moarsheep"
                }
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.OnOff",
                "params": {
                  "on": true
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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.
commands Array

Each object contains one or more devices with response details. N.B. These may not be grouped the same way as in the request. For example, the request might turn 7 lights on, with 3 lights succeeding and 4 failing, thus with two groups in the response.
[item, ...] Object

Device execution result.
ids Array

Required.

List of device IDs corresponding to this status.
[item, ...] String

Device ID.
status String

Required.

Result of the execute operation.

Supported values:

SUCCESS
Confirm that the command succeeded.
PENDING
Command is enqueued but expected to succeed.
OFFLINE
Target device is in offline state or unreachable.
EXCEPTIONS
There is an issue or alert associated with a command. The command could succeed or fail. This status type is typically set when you want to send additional information about another connected device.
ERROR
Target device is unable to perform the command.
states Object

Aligned with per-trait states described in each trait schema reference. These are the states after execution, if available.
online Boolean

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

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

EXECUTE intent response

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      },
      {
        "ids": [
          "456"
        ],
        "status": "ERROR",
        "errorCode": "deviceTurnedOff"
      }
    ]
  }
}