# 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](https://developers.home.google.com/cloud-to-cloud/integration/query-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 response 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. |
| `debugString` | *String* | Detailed command-level error which will never be presented to users but may be logged or used during development. |

##### 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"
      }
    ]
  }
}
```