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

List of objects describing available media channels for this particular device. Each item describes a channel the user can select on this device.

Properties:

key String

Unique identifier for this channel. Not exposed to users.

names Array <String>

List of user-visible names for this channel.

number String

Numeric identifier for this channel.

Required:

  • key
  • names

Required:

  • availableChannels
Examples

Device supporting two channels.

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

Sample SYNC Request and Response

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.TV',
        traits: [
          'action.devices.traits.Channel'
        ],
        name: {
          defaultNames: ['TV'],
          name: 'Living room TV',
          nicknames: ['Big TV']
        },
        willReportState: true,
        attributes: {
          availableChannels: [
            {
              key : 'ktvu2',
              names : [
                'Fox',
                'KTVU'
              ],
              number: '2'
            },
            {
              key : 'abc1',
              names : [
                'ABC',
                'ABC East'
              ],
              number: '702.4-11'
            }
          ]
        },
        deviceInfo: {
          manufacturer: 'Sirius Cybernetics Corporation',
          model: '492134',
          hwVersion: '3.2',
          swVersion: '11.4'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-channel_sync.json")
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");

  payload.setDevices(
      new Device[] {
        new Device.Builder()
            .setId("123")
            .setType("action.devices.types.TV")
            .addTrait("action.devices.traits.Channel")
            .setName(
                Collections.singletonList("TV"),
                "Living room TV",
                Collections.singletonList("Big TV"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "availableChannels",
                        new JSONObject[] {
                          new JSONObject()
                              .put("key", "ktvu2")
                              .put("names", new String[] {"Fox", "KTVU"})
                              .put("number", "2"),
                          new JSONObject()
                              .put("key", "abc1")
                              .put("names", new String[] {"ABC", "ABC East"})
                              .put("number", "702.4-11")
                        }))
            .setDeviceInfo("Sirius Cybernetics Corporation", "492134", "3.2", "11.4")
            .build()
      });

  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [{
      "id": "123",
      "type": "action.devices.types.TV",
      "traits": [
        "action.devices.traits.Channel"
      ],
      "name": {
        "defaultNames": ["TV"],
        "name": "Living room TV",
        "nicknames": ["Big TV"]
      },
      "willReportState": true,
      "attributes": {
        "availableChannels": [
           {
             "key" : "ktvu2",
             "names" : [
               "Fox",
               "KTVU"
             ],
             "number": "2"
           },
           {
             "key" : "abc1",
             "names" : [
               "ABC",
               "ABC East"
             ],
             "number": "702.4-11"
           }
        ]
      },
      "deviceInfo": {
        "manufacturer": "Sirius Cybernetics Corporation",
        "model": "492134",
        "hwVersion": "3.2",
        "swVersion": "11.4"
      }
    }]
  }
}

Validator

Device STATES

None.

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

Parameters

Set the current channel to a specific value.

The payload has exactly one of these:

Select channel by ID
Parameters Type Description
channelCode String

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.

Required:

  • channelCode
Select channel by number
Parameters Type Description
channelNumber String

Numeric identifier for the requested channel.

Required:

  • channelNumber
Examples

Change to KTVU

{
  "channelCode": "ktvu2",
  "channelName": "KTVU"
}

Turn to channel three.

{
  "channelNumber": "3"
}

An error occurred selecting a new channel on the device.

  • noAvailableChannel
  • noChannelSubscription
  • channelSwitchFailed

action.devices.commands.RelativeChannel

Parameters

Adjust the current channel by a relative amount.

Parameters Type Description
relativeChannelChange Integer

The number of channels to increase or decrease.

Required:

  • relativeChannelChange
Examples

Switch to the next channel

{
  "relativeChannelChange": 1
}

Switch to the previous channel

{
  "relativeChannelChange": -1
}

An error occurred adjusting the channel of the device.

  • channelSwitchFailed

action.devices.commands.ReturnChannel

Parameters

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

Parameters
No properties.
Examples

Return to the last channel

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

  • channelSwitchFailed

Sample EXECUTE Request and Response

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.selectChannel",
          "params": {
            "channelName": "KTVU",
            "channelCode": "ktvu2",
            "channelNumber": "2"
          }
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          channelName: 'KTVU',
          channelNumber: '2'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
@SmartHomeSnippetJson("smart-home-traits-channel_execute.json")
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();
  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put("channelName", "KTVU");
                put("channelNumber", "2");
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
         "channelName": "KTVU",
         "channelNumber": "2"
      }
    }]
  }
}

Device ERRORS

See the full list of errors and exceptions.