Alexa.ChannelController Interface
The Alexa.ChannelController
interface exposes directives that are used to change or increment the channel for an entertainment device.
For the list of locales that are supported for the ChannelController
interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.ChannelController
interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, change the channel to 200 on the TV.
Alexa, change the channel to PBS on the cable box.
Alexa, next channel on the TV.
Alexa, channel up on the TV.
Alexa, channel down on the TV.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Directives
ChangeChannel
Request for a channel change by specifying a channel number or call sign.
User: Alexa, change channel to 200 on device
User: Alexa, wechsel auf Gerät zu Kanal zweihundert
User: Alexa, change channel to PBS on device
User: Alexa, wechsel auf Gerät den Kanal zu Arte
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.ChannelController",
"name": "ChangeChannel",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "device-001",
"cookie": {
}
},
"payload": {
"channel": {
"number": "1234",
"callSign": "KSTATION1",
"affiliateCallSign": "KSTATION2",
"uri": "someUrl"
},
"channelMetadata": {
"name": "Alternate Channel Name",
"image": "urlToImage"
}
}
}
}
Payload details
Field | Description | Type | Required |
---|---|---|---|
channel |
Describes a channel. | object | Yes |
channel.number |
A number that identifies the specified channel such as 5 or 12.1 | string | No, but channel.number , channelMetadata.name , channel.callSign , affiliateCallSign or uri must be specified. |
channel.callSign |
Specifies a channel by call sign such as PBS. | string | No, but channel.number , channelMetadata.name , channel.callSign , affiliateCallSign or uri must be specified. |
channel.affiliateCallSign |
Specifies a channel by local affiliate call sign such as KCTS9. | string | No, but channel.number , channelMetadata.name , channel.callSign , channel.affiliateCallSign or channel.uri must be specified. |
channel.uri |
The URI of the channel such as "entity://provider/channel/12307" | string | No, but channel.number , channelMetadata.name , channel.callSign , channel.affiliateCallSign or channel.uri must be specified. |
channelMetadata |
Provides additional information about the specified channel. | object | No |
channelMetadata.name |
Another value that identifies the channel such as "FOX". | string | No, but channel.number , channelMetadata.name , channel.callSign , channel.affiliateCallSign or channel.uri must be specified. |
channelMetadata.image |
A URL to an image that describes the channel. | string | No |
SkipChannels
Request for an incremental channel adjustment in discrete steps using a positive number for a step up, or negative number for a step down.
User: Alexa, next channel on device
User: Alexa, nächsten Kanal auf Gerät
User: Alexa, channel up on device
User: Alexa, einen Kanal vor auf Gerät
User: Alexa, channel down on device
User: Alexa, einen Kanal zurück auf Gerät
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.ChannelController",
"name": "SkipChannels",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"payloadVersion": "3"
},
"payload": {
"channelCount" : 5
}
}
}
Payload details
Field | Description | Type | Required |
---|---|---|---|
channelCount |
An integer value that indicates the channels to increment. A negative number indicates steps down, a positive number a steps up. | integer between -10000 and 10000 | Yes |
Events and Properties
For this capability, you must reply:
- Synchronously, which means you send a Response to Alexa from the Lambda function.
When you send a Response
, you should include the state of the interface properties in the context
of the message.
Properties
Property Name | Property Type | Description |
---|---|---|
channel |
Channel | Specifies a channel by number, call sign or affiliate call sign. |
Response
You must send an Response
event if a request to change or skip channels was successful. The response should include a context object that reports the channel after the request completes.
Response Example
{
"context": {
"properties": [
{
"namespace": "Alexa.ChannelController",
"name": "channel",
"value": {
"number": "1234",
"callSign": "callsign1",
"affiliateCallSign": "callsign2"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
},
"event": {
"header": {
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3"
},
"endpoint":{
"endpointId":"appliance-001"
},
"payload":{ }
}
}
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.
Additional Sample Code
See the sample request and response messages in the Alexa smart home GitHub repo: