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.
{
"name":"channel",
"value": {
"number": "9",
"callSign": "PBS",
"affiliateCallSign": "KCTS"
}
}
The following table shows the definition of the Channel
object.
Property | Description | Type | Required |
---|---|---|---|
|
TV channel number, such as 256 or 13.1. |
String |
No |
|
Call sign of the channel, such as PBS. |
String |
No |
|
Local affiliate call sign of the channel, such as KCTS. |
String |
No |
|
URI of the channel, such as |
String |
No |
Channel
object doesn't require any of the fields. However, you must always specify at least one of channel.number
, channel.callSign
, channel.affiliateCallSign
, channel.uri
, or channelMetadata.name
.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 |
---|---|---|---|
|
Another name for the channel, such as "The CW." |
String |
No |
|
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.
{
"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 |
---|---|---|---|
|
Name of the provider lineup. |
String |
No |
|
Name of the TV provider. |
String |
Yes |
|
Describes the type of lineup. |
String |
Yes |
|
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.ChannelController
interface.
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.
{
"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.
{
"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.
{
"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
{
"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
{
"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
}
]
}
}