Alexa.ChannelController

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

Directives

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

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": "1.0"
    },
    "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": "1.0"
    },
    "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 can 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": "1.0"
    },
    "endpoint":{
       "scope":{
          "type":"BearerToken",
          "token":"Alexa-access-token"
       },
       "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