Alexa.ChannelController Interface

Implement the Alexa.ChannelController interface in your Alexa Smart Home skill so that users can change or increment the channel for an entertainment device. For more information about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.

For the list of languages that the ChannelController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

When you use the Alexa.ChannelController interface, the voice interaction model is already built for you. The following examples show some user utterances:

Alexa, change the channel to 200 on the Living Room TV.
Alexa, change the channel to PBS on the TV.
Alexa, next channel on the Living Room TV.
Alexa, channel up on the TV.
Alexa, channel down on the TV.

After the user says one of these utterances, Alexa sends a corresponding directive to your skill.

Properties

The channel object

The Alexa.ChannelController interface uses the channel property as the primary property. The property values are objects. Use the channel property to specify a channel by number, call sign, or affiliate call sign.

Channel object details

Field Description Type
number The channel number, such as 256 or 13.1. String
callSign The call sign of the channel, such as PBS. String
affiliateCallSign The local affiliate call sign of the channel, such as KCTS. String
uri The URI of the channel, such as entity://provider/channel/12307. String

Channel object example

Copied to clipboard.

{
   "name":"channel",
   "value": {
     "number": "9",
     "callSign": "PBS",
     "affiliateCallSign": "KCTS"
  }
}

The channelMetadata object

The channelMetadata property provides additional information about a channel.

ChannelMetadata object details

Field Description Type
name Another name for the channel, such as "The CW". String
image The URL of an image or logo for the channel. String

ChannelMetadata object example

Copied to clipboard.

{
   "name":"channelMetadata",
   "value": {
     "name": "Alternate channel name",
     "image": "<url for image>"
  }
}

Discovery

You describe endpoints that support Alexa.ChannelController using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

Use TV, STREAMING_DEVICE, GAME_CONSOLE, or other appropriate display category. For the full list of display categories, see display categories.

Discover response example

The following example shows a Discover.Response message for a television that supports the Alexa.ChannelController and Alexa.PowerController interfaces. For the full list of recommended interfaces for a television, see Smart Home Skill Device Templates.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name of the endpoint>",
          "description": "Smart Television by Television Maker",
          "friendlyName": "Living Room TV",
          "displayCategories": ["TV"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ChannelController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "channel"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

ChangeChannel directive

Support the ChangeChannel directive so that users can change the channel on a device by specifying a channel number or call sign.

The following example shows a user utterance:

Alexa, change channel to 200 on Living Room TV.

Alexa, wechsel auf Wohnzimmer TV zu Kanal zweihundert.

ChangeChannel directive payload details

Field Description Type
channel The channel to change the device to. A channel object.
channelMetadata Additional information about the channel to change the device to. A channelMetadata object.

ChangeChannel directive example

The following example illustrates a ChangeChannel directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "ChangeChannel",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "channel": {
        "number": "9",
        "callSign": "PBS",
        "affiliateCallSign": "KCTS",
        "uri": "<channel uri>"
      },
      "channelMetadata": {
        "name": "Alternate channel name",
        "image": "<url for image>"
      }
    }
  }
}

ChangeChannel response event

If you handle a ChangeChannel directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.

ChangeChannel response event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": "9",
          "callSign": "PBS",
          "affiliateCallSign": "KCTS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

ChangeChannel directive error handling

If you can't handle a ChangeChannel directive successfully, respond with an Alexa.ErrorResponse event.

SkipChannels directive

Support the SkipChannels directive so that users can change the channel on a device incrementally in a discrete step. Users can use a positive number for a step up, or negative number for a step down.

The following example shows a user utterance:

Alexa, next channel on Living Room TV
Alexa, channel up on Living Room TV
Alexa, channel down on Living Room TV

Alexa, nächsten Kanal auf Wohnzimmer TV
Alexa, einen Kanal vor auf Wohnzimmer TV
Alexa, einen Kanal zurück auf Wohnzimmer TV

SkipChannels directive payload details

Field Description Type
channelCount The number of channels to increment by. A negative number changes the channel down, a positive number changes the channel up. An integer. Currently the only allowed values are 1 and -1.

SkipChannels directive example

The following example illustrates a SkipChannels directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "SkipChannels",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "payload": {
      "channelCount" : 1
    }
  }
}

SkipChannels response event

If you handle a SkipChannels directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed.

SkipChannels response event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": "7",
          "callSign": "CBS",
          "affiliateCallSign": "KIRO"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

SkipChannels directive error handling

If you can't handle a SkipChannels directive successfully, respond with an Alexa.ErrorResponse event.

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all of the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

StateReport response event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": "7",
          "callSign": "CBS",
          "affiliateCallSign": "KIRO"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

ChangeReport event example

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "VOICE_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ChannelController",
            "name": "channel",
            "value": {
              "number": "9",
              "callSign": "PBS",
              "affiliateCallSign": "KCTS"
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}