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.number
, channel.callSign
, channel.affiliateCallSign
, channel.uri
, or channelMetadata.name
must always be specified.Channel object example
{
"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 |
channel.number
, channel.callSign
, channel.affiliateCallSign
, channel.uri
, or channelMetadata.name
must always be specified.ChannelMetadata object example
{
"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.
{
"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. |
channel.number
, channel.callSign
, channel.affiliateCallSign
, channel.uri
, or channelMetadata.name
is always specified in the directive.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
{
"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
{
"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
{
"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
{
"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
}
]
}
}