# Smart Home Channel Trait Schema

`action.devices.traits.Channel` - This trait belongs to devices that support TV channels on a media device.
The available channels should be shared as a list, per user or device, during SYNC via the `availableChannels` attribute. This list should comprise of all top or popular channels that the user or device is subscribed to. To ensure a low query latency, we recommend that you keep the channel list small (to 30 channels or less).

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| Attributes | Type | Description |
|---|---|---|
| `availableChannels` | *Array* | **Required.** List of objects describing available media channels for this particular device. Each item describes a channel the user can select on this device. |
| `[*item, ...*]` | *Object* | Available media channel. |
| `key` | *String* | **Required.** Unique identifier for this channel. Not exposed to users. |
| `names` | *Array* | **Required.** List of user-visible names for this channel. |
| `[*item, ...*]` | *String* | Channel name. |
| `number` | *String* | Optional numeric identifier for this channel. |
| `commandOnlyChannels` | *Boolean* | (Default: `false`) Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait. |

#### Examples

*Device supporting two channels.*

```
{
  "availableChannels": [
    {
      "key": "ktvu2",
      "names": [
        "Fox",
        "KTVU"
      ],
      "number": "2"
    },
    {
      "key": "abc1",
      "names": [
        "ABC",
        "ABC East"
      ],
      "number": "4-11"
    }
  ]
}
```

## Device STATES

None.

## Device COMMANDS

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `action.devices.commands.selectChannel`

Set the current channel to a specific value.

#### Parameters

The payload contains one of the following:

#### Select channel by ID

| Parameters | Type | Description |
|---|---|---|
| `channelCode` | *String* | **Required.** Unique identifier for the requested channel, matching one of the `availableChannels`. |
| `channelName` | *String* | User-friendly name of the requested channel. |
| `channelNumber` | *String* | Numeric identifier for the requested channel. |

#### Select channel by number

| Parameters | Type | Description |
|---|---|---|
| `channelNumber` | *String* | **Required.** Numeric identifier for the requested channel. |

#### Examples

*Change to KTVU*

```
{
  "command": "action.devices.commands.selectChannel",
  "params": {
    "channelCode": "ktvu2",
    "channelName": "KTVU"
  }
}
```

*Turn to channel three.*

```
{
  "command": "action.devices.commands.selectChannel",
  "params": {
    "channelNumber": "3"
  }
}
```

#### Related errors

An error occurred selecting a new channel on the device.

Supported values:

`noAvailableChannel`
`noChannelSubscription`
`channelSwitchFailed`

### `action.devices.commands.relativeChannel`

Adjust the current channel by a relative amount.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `relativeChannelChange` | *Integer* | **Required.** The number of channels to increase or decrease. |

#### Examples

*Switch to the next channel*

```
{
  "command": "action.devices.commands.relativeChannel",
  "params": {
    "relativeChannelChange": 1
  }
}
```

*Switch to the previous channel*

```
{
  "command": "action.devices.commands.relativeChannel",
  "params": {
    "relativeChannelChange": -1
  }
}
```

#### Related errors

An error occurred adjusting the channel of the device.

Supported values:

`channelSwitchFailed`

### `action.devices.commands.returnChannel`

Return to the last/previous channel the user was on.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| No properties |||

#### Examples

*Return to the last channel*

```
{
  "command": "action.devices.commands.returnChannel",
  "params": {}
}
```

#### Related errors

An error occurred returning to the last channel of the device.

Supported values:

`channelSwitchFailed`

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).