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 operation. To learn more about handling SYNC intents, see Intent fulfillment.

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 operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

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

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
  }
}

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

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

Supported values:

channelSwitchFailed

Device ERRORS

See the full list of errors and exceptions.