Developer Console

Alexa.ChannelController Interface (VSK Fire TV)

When users say utterances to change the channel (e.g., "Alexa, change the channel to PBS"), the Alexa.ChannelController interface sends ChangeChannel directives to indicate that the channel should be changed. These directives are sent when users specify the channel name, call sign, or channel number.

Utterances for ChannelController Directives

Alexa sends a ChangeChannel directive through the ChannelController interface to your Lambda when users say the following utterances.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

Go to fox

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

Go to channel thirteen

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

Go to channel k. c. p. q.

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

Watch fox

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

Watch channel thirteen

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

Va sur [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

va sur [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

cambia canal a t. p. d.

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

mets [ChannelName]

joue [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

mets la chaîne[ChannelNumber]

joue la chaîne[ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

Va sur [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

va sur [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

va sur [channel]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

mets [ChannelName]

joue [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

mets la chaîne[ChannelNumber]

joue la chaîne[ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

(schalt auf|geh zu) [ChannelName]

schalt kanal [ChannelName] ein

(geh|schalt|wechsel|änder) zum kanal [ChannelName]

(geh|schalt|wechsel|änder) zu [ChannelName] kanal

(wechsel|änder) den kanal zu [ChannelName]

(wechsel|änder) den kanal zu [ChannelName] auf [AppName]

schalt [ChannelName] auf [AppName] an

schalt kanal [ChannelName] auf [AppName] an

(geh|schalte|wechsel) zu [ChannelName] auf [AppName]

(stell|schalt) [ChannelName] ein auf [AppName]

(stell|schalt|wechsel) (um zu|auf) [ChannelName] auf [AppName]

schalt kanal [ChannelName] auf [AppName] an

mach [ChannelName] auf [AppName] an

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

schalt kanal [ChannelNumber] ein

(geh|schalt|wechsel|änder) zum kanal [ChannelNumber]

(geh|schalt|wechsel|änder) zu [ChannelNumber] kanal

(wechsel|änder) den kanal zu [ChannelNumber]

(wechsel|änder) den kanal zu [ChannelNumber] auf [AppName]

schalt [ChannelNumber] auf [AppName] an

schalt kanal [ChannelNumber] auf [AppName] an

(geh|schalte|wechsel) zu [ChannelNumber] auf [AppName]

(stell|schalt) [ChannelNumber] ein auf [AppName]

(stell|schalt|wechsel) (um zu|auf) [ChannelNumber] auf [AppName]

schalt kanal [ChannelNumber] auf [AppName] an

mach [ChannelNumber] auf [AppName] an

kanal [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

schalte/änder/geh zu/auf den fernsehsender [ChannelName]

geh zum (fernseh)kanal [ChannelName]

ändern den (fernseh)kanal zu/auf [ChannelName]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

[ChannelName] auf [AppName] ansehen

spiel den kanal [ChannelName] ab

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

Zeige Kanal/Sender [channel number]

Kanal/Sender [channel number] anschauen

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

fox पर/पे जाओ/जाइए/जाना/चलो/चलना

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

channel दस पर/पे जाओ/जाना/जाइए/चलो/चलना

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

channel sony पर/पे जाओ/जाना/जाइए/चलो/चलना

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

fox देखो/देखिए/देखना/देखें

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

channel बारह देखो/देखना/देखिए/देखें

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

vai su [ChannelName]

vai a [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

vai al [ChannelNumber]

vai su [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

vai su [Channel]

vai a [Channel]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

guarda [ChannelName]

fammi vedere [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

metti [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

[ChannelName]を検索

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

[ChannelName]を見せて

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

チャンネル[ChannelNumber]を見せて

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

vá/vai/ir para o canal [ChannelName]

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

vá para o canal [CallSign]

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

assistir/assiste/assista [ChannelName]Assistir/assiste/assistao [ChannelName]

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

assitir canal [ChannelNumber]

The view switches to the channel number, and content from the channel plays.

Feature Sample Utterances Expected Response
Go to channel name
Required for certification

cambia a antena tres

The view switches to the channel name, and content from the channel plays.

Go to channel number
Required for certification

cambia el canal a la dos

The view switches to the channel number, and content from the channel plays.

Go to channel callsign
Required for certification

cambia canal a t. p. d.

The view switches to the channel callsign, and content from the channel plays.

Watch channel name
Required for certification

ver la sexta

pon la sexta

The view switches to the channel name, and content from the channel plays.

Watch channel number
Required for certification

pon canal dos

The view switches to the channel number, and content from the channel plays.

ChangeChannel Directive Example

The following is an example ChangeChannel directive:

EXTRA_DIRECTIVE_NAMESPACE: Alexa.ChannelController
EXTRA_DIRECTIVE_NAME: ChangeChannel
EXTRA_DIRECTIVE_PAYLOAD_VERSION: 3
EXTRA_DIRECTIVE_PAYLOAD: payload

payload contains the following:

{
    "payload": {
      "experience": {
         "mode": "VOICE_OPTIMIZED",
              },
      "channel": {
          "number": "1234",
          "callSign": "KSTATION1",
          "affiliateCallSign": "KSTATION2",
          "uri": "someUrl"
      },
      "channelMetadata": {
          "name": "Alternate Channel Name",
          "image": "urlToImage"
      }
    }
  }
{
  "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": {
      "experience": {
          "mode": "VOICE_OPTIMIZED",
              },
      "channel": {
          "number": "1234",
          "callSign": "KSTATION1",
          "affiliateCallSign": "KSTATION2",
          "uri": "someUrl"
      },
      "channelMetadata": {
          "name": "Alternate Channel Name",
          "image": "urlToImage"
      }
    }
  }
}

Payload Definitions

Field Description Type Required
experience An object that optimizes the display of search results. Experience Types for more details. object No
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

Experience Types

Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote.

The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.

  • VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.

  • DEFAULT: The default displays of all search results list format, regardless of the device used for the search.

To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

Handling ChangeChannel Directives

The ChangeChannel directive allows customers to tune to a specific channel using voice commands. When users say "Alexa, tune to CNN," you receive a ChangeChannel directive in your Lambda. You then need to change the live TV stream to show the user the correct channel.

To help you understand which directive corresponds with which channel, we have provided a list of possible callsigns for each channel in Channels List.

If you'd like to support additional channels not included in this list, reach out to your Amazon contact, and he or she will coordinate with the right people to get you the information you need on how to handle it.

Alternatively, try asking your Alexa-enabled device to change the channel to whichever channel you like, and then observe the directive received in your Lambda log to check the callsign for yourself. However, it's still best if you flag those channels to your Amazon contact so we can know to prioritize that channel in our voice models. The channel callsign will be available within the callSign field within the channel change directive's payload.

You will not receive information about local channels in the directives — just top level names and callsigns, such as "ABC." It is up to you to perform any localization for your users.

Response Example

You must send an Response event if a request to change channels was successful. The response should include a context object that reports the channel after the request completes.

{
  "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":{ }
 }
}

If you cannot complete the customer request for some reason, reply with an error. See Error Handling for more details.


Last updated: Jun 09, 2021