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 or video device. For details about entertainment device skills, see Build Smart Home Skills for Entertainment Devices and Understand Video Skills.

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

Utterances

The Alexa.ChannelController interface uses the pre-built voice interaction model. The following examples show some user utterances:

Alexa, change the channel to two hundred 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.

Alexa, schalte den Wohnzimmer TV auf Kanal zweihundert.
Alexa, nächster Sender auf Wohnzimmer TV.
Alexa, vorheriger Sender auf Wohnzimmer TV.
Alexa, einen Sender nach unten auf Wohnzimmer TV.

アレクサ、チャンネル4に変えて
アレクサ、テレビをチャンネル1にして
アレクサ、次のチャンネル
アレクサ、前のチャンネルに戻って

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

Properties and objects

Reportable properties

The Alexa.ChannelController interface uses the channel property as the primary property. You identify that you support the property in your discovery response.

Channel property

The channel property specifies a channel by number, call sign, or affiliate call sign. The channel property value is an object.

The following example shows the channel property.

Copied to clipboard.

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

The following table shows the definition of the Channel object.

Property Description Type Required

number

TV channel number, such as 256 or 13.1.

String

No

callSign

Call sign of the channel, such as PBS.

String

No

affiliateCallSign

Local affiliate call sign of the channel, such as KCTS.

String

No

uri

URI of the channel, such as entity://provider/channel/12307.

String

No

ChannelMetadata object

The ChannelMetadata property provides additional information about a channel.

The following example shows a ChannelMetadata object.

Copied to clipboard.

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

The following table shows the definition of the channelMetadata object.

Property Description Type Required

name

Another name for the channel, such as "The CW."

String

No

image

URL of an image or logo for the channel.

String

No

Lineup object

Live TV providers, such as multichannel video programming distributors (MVPDs), might want to build an Alexa skill that can provide different channel lineups per user or zip code. A lineup is a set of TV channels based on a combination of stations, affiliate, and channel number.

Alexa finds the TV channel lineup based on the parameters defined in the Lineup object. You specify the lineup information in your discovery response. If you change the lineup, you must send an AddOrUpdateReport.

The following example shows a Lineup object.

Copied to clipboard.

{
    "lineup": {
        "operatorName": "Comcast Corporation",
        "type": "multiSystemOperator",
        "lineupName": "Comcast King County South - Digital",
        "postalCode": "98109"
    }
}

The following table shows the definition of the Lineup object.

Property Description Type Required

lineupName

Name of the provider lineup.

String

No

operatorName

Name of the TV provider.

String

Yes

type

Describes the type of lineup.
Valid values: overTheAir, multiSystemOperator, streamingOperator.

String

Yes

postalCode

Specifies the postal or zip code where the customer resides.

String

No

Discovery

You describe endpoints that support Alexa.ChannelController by 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, Alexa.PowerController, and Alexa.EndpointHealth interfaces. For the full list of recommended interfaces for a television, see Smart Home Skill Device Templates.

Discover response with lineup example

The following example shows a Discover.Response message for an MVPD that supports different channel lineups per user or zip code. The example includes lineup information in the Alexa.ChannelControllerinterface.

AddOrUpdateReport

When a user adds a new endpoint to their account, or there are changes to an existing endpoint, you must send an Alexa.Discovery.AddOrUpdateReport message proactively to the Alexa event gateway. You can include all the endpoints associated with the user account, or only the new or updated endpoints. You can choose based on your skill implementation. For details, see AddOrUpdateReport.

AddOrUpdateReport example

The following example shows an AddOrUpdateReport message for a new endpoint.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "a unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the new endpoint",
                "manufacturerName": "the manufacturer name of the endpoint",
                "description": "a description that is shown in the Alexa app",
                "friendlyName": "Living Room TV",
                "displayCategories": ["TV"],
                "additionalAttributes": {
                    "manufacturer": "the manufacturer name of the endpoint",
                    "model": "the model of the device",
                    "serialNumber": "the serial number of the device",
                    "firmwareVersion": "the firmware version of the device",
                    "softwareVersion": "the software version of the device"
                },
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ChannelController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "channel"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }],
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            }
        }
    }
}

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 two hundred on Living Room TV.

Alexa, schalte den Wohnzimmer TV auf Kanal zweihundert.

アレクサ、チャンネル4に変えて

ChangeChannel directive example

The following example shows 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 directive payload

The following table shows the payload details for the ChangeChannel directive.

Property Description Type
channel The channel to change the device to. Channel object
channelMetadata Additional information about the channel to change the device to. ChannelMetadata object

ChangeChannel response

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.

The following example shows a ChangeChannel response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "a unique identifier, preferably a version 4 UUID",
      "correlationToken": "an opaque correlation token that matches the request",
      "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 and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic 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ächster Sender auf Wohnzimmer TV.
Alexa, vorheriger Sender auf Wohnzimmer TV.
Alexa, einen Sender nach unten auf Wohnzimmer TV.

アレクサ、テレビを次のチャンネルにして
アレクサ、次のチャンネル
アレクサ、前のチャンネルに戻って

SkipChannels directive example

The following example shows 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 directive payload

The following table shows the payload details for the SkipChannels directive.

Property Description Type
channelCount Number of channels to increment by. A negative number changes the channel down, a positive number changes the channel up.
Valid values: –1 and 1		 Integer

SkipChannels response

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.

The following example shows a SkipChannels response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "a unique identifier, preferably a version 4 UUID",
     "correlationToken": "an opaque correlation token that matches the request",
      "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 and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic 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 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 example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "a unique identifier, preferably a version 4 UUID",
      "correlationToken": "an opaque correlation token that matches the request",
      "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
    },
    {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
            "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
    }
    ]
  }
}

Change reporting

You send a ChangeReport event to report changes proactively 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": "a unique identifier, preferably a version 4 UUID",
            "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
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}