Alexa.ChannelController Interface 3

Implement the Alexa.ChannelController interface in your Alexa add-on so that users can change or increment the channel for an entertainment or video device. For details about entertainment device add-ons, see Connect Your Device Cloud with Smart Home Add-ons 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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.ChannelController interface uses the pre-built voice interaction model. After the customer says one of the following utterances, Alexa sends a corresponding directive to your add-on. The following examples show some user utterances:

Properties and objects

The Alexa.ChannelController interface includes the following 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.

{
   "name":"channel",
   "value": {
     "number": "9",
     "callSign": "KCTS-TV",
     "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 WKCTS-TV.	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.

{
   "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 add-on 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.

{
    "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 add-on 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. To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

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 Device Templates.

Show/hide Discovery response

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Manufacturer 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.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

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.

Show/hide Discovery response with lineup

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Manufacturer 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
                        },
                        "lineup": {
                            "operatorName": "Comcast Corporation",
                            "type": "multiSystemOperator",
                            "lineupName": "Comcast King County South - Digital",
                            "postalCode": "98109"
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PowerController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "powerState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

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 add-on implementation. For details, see AddOrUpdateReport.

AddOrUpdateReport example

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "unique ID of the new endpoint",
                "manufacturerName": "Manufacturer of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Living Room TV",
                "displayCategories": ["TV"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "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.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }],
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            }
        }
    }
}

Directives

Alexa sends the following Alexa.ChannelController interface directives to your add-on.

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:

English (All)
German
Japanese

ChangeChannel directive example

The following example shows a ChangeChannel directive that Alexa sends to your add-on.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "ChangeChannel",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "channel": {
        "number": "9",
        "callSign": "KCTS-TV",
        "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. A successful response confirms that the endpoint completed the requested action. In the context object, include the values of all properties that changed. The following example shows a ChangeChannel response.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "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": "KCTS-TV",
          "affiliateCallSign": "KCTS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "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:

English (All)
German
Japanese

SkipChannels directive example

The following example shows a SkipChannels directive that Alexa sends to your add-on.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "SkipChannels",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "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. A successful response confirms that the endpoint completed the requested action. In the context object, include the values of all properties that changed. The following example shows a SkipChannels response.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
     "correlationToken": "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": "KIRO-TV",
          "affiliateCallSign": "KIRO"
        },
        "timeOfSample": "2017-02-03T16:25:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": "7",
          "callSign": "KIRO-TV",
          "affiliateCallSign": "KIRO"
        },
        "timeOfSample": "2017-02-03T17:00:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:18:40.12Z",
        "uncertaintyInMilliseconds": 500
    },
    {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
            "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:15:00.00Z",
        "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

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "Endpoint ID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "VOICE_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.ChannelController",
                    "name": "channel",
                    "value": {
                        "number": "9",
                        "callSign": "KCTS-TV",
                        "affiliateCallSign": "KCTS"
                    },
                    "timeOfSample": "2017-02-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": "ON",
                "timeOfSample": "2017-02-03T16:18:40.12Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:15:00.00Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Properties and objects

Reportable properties

Channel property

ChannelMetadata object

Lineup object

Discovery

Discover response example

Discover response with lineup example

AddOrUpdateReport

AddOrUpdateReport example

Directives

ChangeChannel directive

ChangeChannel directive example

ChangeChannel directive payload

ChangeChannel response

ChangeChannel directive error handling

SkipChannels directive

SkipChannels directive example

SkipChannels directive payload

SkipChannels response

SkipChannels directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

​Utterances

​Properties and objects

​Reportable properties

​Channel property

​ChannelMetadata object

​Lineup object

​Discovery

​Discover response example

​Discover response with lineup example

​AddOrUpdateReport

​AddOrUpdateReport example

​Directives

​ChangeChannel directive

​ChangeChannel directive example

​ChangeChannel directive payload

​ChangeChannel response

​ChangeChannel directive error handling

​SkipChannels directive

​SkipChannels directive example

​SkipChannels directive payload

​SkipChannels response

​SkipChannels directive error handling

​State reporting

​StateReport response example

​Change reporting

​ChangeReport event example

​Related topics

Utterances

Properties and objects

Reportable properties

Channel property

ChannelMetadata object

Lineup object

Discovery

Discover response example

Discover response with lineup example

AddOrUpdateReport

AddOrUpdateReport example

Directives

ChangeChannel directive

ChangeChannel directive example

ChangeChannel directive payload

ChangeChannel response

ChangeChannel directive error handling

SkipChannels directive

SkipChannels directive example

SkipChannels directive payload

SkipChannels response

SkipChannels directive error handling

State reporting

StateReport response example

Change reporting

ChangeReport event example

Related topics