Alexa.ChannelController

The ChannelController interface exposes directives that are used to change or increment the channel for an entertainment device.

Directives
- ChangeChannel
- SkipChannels
Events and Properties
Additional Sample Code

Directives

This control and query directives in this interface are supported in skills that target the following languages:

English (US)
English (UK) (video skills)

See Develop Smart Home Skills in Multiple Languages for more information. for more information.

ChangeChannel

Request for a channel change by specifying a channel number or call sign.

“Alexa, change channel to 200 on device”

“Alexa, change channel to PBS on device”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "ChangeChannel",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "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.

“Alexa, next channel on device”

“Alexa, channel up on device”

“Alexa, channel down on device”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ChannelController",
      "name": "SkipChannels",
      "messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
      "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 interface, you must reply:

Synchronously, which means you send a Response to Alexa in from the Lambda function.

When you send a Response, you should include the state of reportable properties in the context of the message

Reportable 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": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "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 Error.Response for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

ChannelController