Alexa.KeypadController Interface (VSK Fire TV)

When users make requests to select or scroll through onscreen elements, the Alexa.KeypadController interface sends a SendKeystroke directive with a keystroke value (e.g., UP, DOWN) to your app or Lambda.

Warning: Unless you want to customize the way Fire TV already handles in-app voice scrolling and selection, you can skip implementing this interface. See the next section, KeypadController versus Built-in Scrolling and Selection Functionality for details.

KeypadController versus Built-in Scrolling and Selection Functionality
Utterances for SendKeystroke Directives
SendKeystroke Directive Example
Payload Descriptions
Response Example
Declaring Capability Support for this Interface

KeypadController versus Built-in Scrolling and Selection Functionality

Fire TV already offers In-App Voice Scrolling and Selection as built-in functionality that most apps (whether VSK-integrated or not) receive for free on Fire TV. With this built-in functionality, Fire TV tries to guess how far it should scroll when a user says a scroll command (e.g., "Alexa, scroll right" or "Alexa, select this").

The in-app voice scrolling and selection works by mapping D-pad navigation events to your voice commands. D-pad refers to the remote control's directional keypad (the "Navigation" ring around the Select button), which is used to scroll right, left, up, and down. Alexa converts these voice commands into D-pad navigation events that are sent to the app.

KeypadController provides similar functionality but lets you control the scrolling and selection. If you declare KeypadController capability for your app, then the built-in voice scrolling and selection becomes inactive and KeypadController takes priority. You will receive the scrolling and selection directives directly in your app or Lambda, and you can fulfill the request. However, there usually isn't a strong reason for implementing KeypadController over the built-in functionality already provided by Fire TV.

Utterances for SendKeystroke Directives

Users can make utterances related to the following:

Moving in a D-pad directions
Selecting the element that has focus
Scrolling through elements such as lists, menu items, titles, and descriptions
Showing information that is currently offscreen

Alexa sends SendKeystroke directives to your app (for app-only integrations) or to your Lambda (for cloudside integrations) when users say the following utterances.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	Go up go down go left go right	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	Move up move down move left move right	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	Scroll up scroll down scroll left scroll right	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	Page up page down page left page right	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	Up Down Left Right	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	Select this	Whatever is in focus gets selected.
Show/see more Optional	Show more	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	Show details	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	va vers le haut monte vers le haut remonte va en bas descends faire défiler vers le bas va à gauche aller à gauche va à droite aller à droite	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	va vers le haut monte vers le haut remonte navigue en bas navigue vers le bas Naviguer à gauche Naviguer vers la gauche Naviguer à droite Naviguer vers la droite	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	fais défiler vers le haut fais défiler en haut faire défiler vers le bas défiler vers le bas se déplacer vers le bas fais défiler à gauche faire défiler à gauche défiler à gauche se déplacer à droite fais défiler à droite faire défiler à droite défiler à droite se déplacer à droite	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	page vers le haut Page vers le bas Page vers la gauche Page vers la droite	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	va en haut monte faire défiler vers le haut va en bas descends faire défiler vers le bas fais défiler à gauche va à gauche faire défiler à gauche se déplacer à gauche aller à gauche défiler à gauche fais défiler à droite va vers la droite fais défiler vers la droite déplace-toi vers la droite aller à droite défile à droite	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	sélectionne ça choisis ça	Whatever is in focus gets selected.
Show/see more Optional	montre moi en plus montre en plus encore	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	montre des détails montre moi des détails voir plus d'infos	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	va vers le haut monte vers le haut remonte va en bas descends faire défiler vers le bas va à gauche aller à gauche va à droite aller à droite	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	va vers le haut monte vers le haut remonte navigue en bas navigue vers le bas Naviguer à gauche Naviguer vers la gauche Naviguer à droite Naviguer vers la droite	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	fais défiler vers le haut fais défiler en haut faire défiler vers le bas défiler vers le bas se déplacer vers le bas fais défiler à gauche faire défiler à gauche défiler à gauche se déplacer à droite fais défiler à droite faire défiler à droite défiler à droite se déplacer à droite	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	page vers le haut Page vers le bas Page vers la gauche Page vers la droite	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	va en haut monte faire défiler vers le haut va en bas descends faire défiler vers le bas fais défiler à gauche va à gauche faire défiler à gauche se déplacer à gauche aller à gauche défiler à gauche fais défiler à droite va vers la droite fais défiler vers la droite déplace-toi vers la droite aller à droite défile à droite	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	sélectionne ça choisis ça	Whatever is in focus gets selected.
Show/see more Optional	montre moi en plus montre en plus encore	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	montre des détails montre moi des détails voir plus d'infos	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	geh/e nach oben nach oben/rauf/hinauf/hoch gehen gehe hoch geh rauf/hinauf nach unten/runter/hinunter gehen geh runter/nach unten/hinunter geh nach links geh nach rechts	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	nach oben bewegen nach unten bewegen nach links bewegen nach rechts bewegen	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	scroll hoch scroll nach oben scroll rauf scrolle hinauf scrolle hoch scroll hier/dahin/dorthin runter scroll zum letzten runter scroll runter/hinunter/nach unten runter/hinunter/nach unten scrollen scroll nach links scroll links scroll nach rechts scroll rechts	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	seite nach oben seite rauf seite hinauf seite hoch blätter hoch blätter runter seite runter/hinunter/nach unten blätter links seite nach links seite links blätter rechts seite nach rechts seite rechts	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	nach oben bewegen bätter hoch geh hoch scroll hoch scroll nach oben nach unten bewegen blätter runter scroll hier/dahin/dorthin runter geh runter/nach unten scroll hinunter/nach unten runter/hinunter gehen seite runter/hinunter/nach unten nach links bewegen blätter links seite nach? links scroll nach? links geh nach links nach rechts bewegen blätter rechts seite nach? rechts scroll nach? rechts geh nach rechts	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	nimm das wähl das aus? klick die an diese	Whatever is in focus gets selected.
Show/see more Optional	mehr ansehen/sehen zeig mir mehr zeig mir mehr davon zeig mir mehr auf [AppName] zeig mir mehr filme an?	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	details ansehen/sehen zeig details an liefere/gib mir mehr details mehr details	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	ऊपर जाओ ऊपर करो नीचे जाओ * नीचे जाना * ambiguity with "move down" left जाना बाएं जाओ * left पे जाओ * ambiguity with "move left" right जाना right पे जाओ दायें जाओ ambiguity with "move right"	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	ऊपर जाओ ऊपर करो नीचे जाओ * नीचे जाना * ambiguity with "move down" left जाना बाएं जाओ * left पे जाओ * ambiguity with "move left" right जाना right पे जाओ दायें जाओ ambiguity with "move right"	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	उपर चलो ऊपर scroll ऊपर करो नीचे scroll करें नीचे की तरफ scroll करो scroll down करो left scroll करो left की तरफ scroll करो बायें की तरफ scroll करो right scroll करो right की तरफ scroll करो दाएँ की तरफ scroll करो	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	पेज ऊपर करो पेज नीचे करो पेज को left पे ले जाओ पेज को right पे ले जाओ पेज को बाएँ ले जाओ पेज को दाएँ ले जाओ page नीचे करो page down करो page को बाएँ कर दो page left करो page को दाएँ करो page right करो	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	ऊपर ऊपर जाओ उपर चलो ऊपर करो नीचे नीचे जाओ नीचे चलो नीचे करो left बाएँ जाओ बाएँ बाएँ करो Right दाएँ जाओ दाएँ दाएँ करो	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	इसे चुनो इसको select करो	Whatever is in focus gets selected.
Show/see more Optional	और दिखाओ	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	details दिखाओ जानकारी दिखाओ	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	vai su Vai giù / scendi voglio andare verso sinistra voglio andare verso destra	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	salta su Passa giù /passa in giù/salta giù / scendi/ salta verso il basso voglio andare verso sinistra voglio andare verso destra	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	scorri verso l'alto scorri giù / scorri verso il basso /scrolla giù scorri verso sinistra scorri verso destra	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	pagina in su pagina di sotto pagina sinistra/pagina di sinistra pagina destra/pagina di destra	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	su giù verso sinistra verso destra	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	seleziona questo scegli questo	Whatever is in focus gets selected.
Show/see more Optional	mostra mi di più	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	fornisci dettagli mostra più dettagli mostra i dettagli	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	上に行って下に行って左側に行って右の方へ行って	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	上に移動して下の方へ移動して左の方へ移動して右側に移動して	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	上にスクロールして下にスクロールして左の方にスクロールして右側へスクロールして	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	画面の上部へページの下へ画面の左へページの右の方へ	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	上^* 下左^* 右^*	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	これ選んで	Whatever is in focus gets selected.
Show/see more Optional	もっと見せて	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	詳細を表示して	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	Subir/suba/sobe Vá/vai/ir para baixo Vá/vai/ir para esquerda Vá/vai/ir para direita	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	Mover/mova/move pra cima Mova/move/mover para baixo Mova/move/mover para a esquerda Mova/move/mover para direita	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	Rolar/rola/role para cima Rola/role/rolar para baixo Rola/role/rolar para a esquerda Rola/role/rolar para a direita	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	página para cima/ ir para cima na página Página para baixo Pagina para esquerda Página para direita	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	Ir/vai/vá pra cima Ir/vai/vá pra baixo Ir/vai/vá pra esquerda Ir/vai/vá pra direita	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	escolher isso/esse/essa selecionar isso/essa/ esse esse aqui / esse/ essa aqui/ essa/ isso aqui/ isso	Whatever is in focus gets selected.
Show/see more Optional	Mostrar/mostra/mostre mais	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	ver todos os detalhes do progama/show	More details are shown. For example, if information is truncated, more information are shown.

Feature	Sample Utterances	Expected Response
Directional navigation - go Required for certification	ve te arriba ve te abajo ve te a la izquierda ve a la izquierda ve te a la derecha ve a la derecha	The app goes to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional navigation - move Required for certification	muéve te hacia arriba muéve te hacia abajo muéve te hacia izquierda muéve te hacia derecha	The app moves to the left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional scrolling Required for certification	despláza te hacia arriba despláza te para arriba despláza te hacia abajo despláza te para abajo despláza te hacia izquierda despláza te para izquierda despláza te hacia derecha despláza te para derecha	The app scrolls left, right, up, or down, similar pressing the same direction on the D-pad controller.
Directional pagination Required for certification	arriba de la página abajo de la página izquierda de la página derecha de la página	The app pages left, right, up, or down, similar pressing the same direction on the D-pad controller.
Verbless directional navigation Required for certification	ve te arriba ve te abajo izquierda ve te a la derecha ve a la derecha	The app shifts left, right, up, or down, similar pressing the same direction on the D-pad controller.
Select/choose this (that) Required for certification	selecciona esto selecciona este selecciona aquel	Whatever is in focus gets selected.
Show/see more Optional	muestra más muestra qué más hay quiero ver algo más veamos un poco más veamos algo más	More items are shown. For example, if a list shows only a limited number of items, more will be retrieved and shown.
Show/see details (info) Optional	muestra detalles enseña detalles ver detalles	More details are shown. For example, if information is truncated, more information are shown.

SendKeystroke Directive Example

The following is an example KeyStroke directive sent by the KeypadController interface:

App-only Integrations
Cloudside Integrations

EXTRA_DIRECTIVE_NAMESPACE: Alexa.KeypadController
EXTRA_DIRECTIVE_NAME: KeyStroke
EXTRA_DIRECTIVE_PAYLOAD_VERSION: 3
EXTRA_DIRECTIVE_PAYLOAD: payload

payload contains the following:

{
    "payload": {
      "keystroke": "SELECT"
    }
}

{
  "directive": {
    "header": {
      "namespace": "Alexa.KeypadController",
      "name": "SendKeystroke",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "keystroke": "SELECT"
    }
  }
}

Payload Descriptions

The SendKeystroke directive uses the keystroke property in the payload to specify what action should be taken.

Field	Description	Type
`keystroke`	The keystroke requested by the user.	String

Possible values for keystroke include the following: UP, DOWN, LEFT, RIGHT, SELECT, PAGE_UP, PAGE_DOWN, PAGE_LEFT, PAGE_RIGHT, INFO, and MORE. These values are described in the following table.

Keystroke type	Keystroke values	Description
Directional pad (d-pad)	`UP`, `DOWN`, `LEFT`, `RIGHT`, `SELECT`	Move up, down, left, or right one unit or to the next onscreen element, or select the element or item that has focus.
Scrolling	`PAGE_UP`, `PAGE_DOWN`, `PAGE_LEFT`, `PAGE_RIGHT`	Scroll in the specified direction.
Information	`INFO`, `MORE`	Display more information about the onscreen element that currently has focus. For example, show content that is offscreen, or jump to a detail page.

Response Example

If you handle a SendKeystroke directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.

App-only Integrations
Cloudside Integrations

First Tab

Second tab

SendKeystroke response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  }
}

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

Declaring Capability Support for this Interface

App-only Integrations
Cloudside Integrations

To receive KeypadController directives in your app, you must indicate support for this interface when you declare your capabilities. See the following for more information on declaring capabilities with app-only integrations:

To indicate that your video skill supports the Alexa.KeypadController interface, you must indicate support for it in your response to the Discover directive sent through the Alexa.Discovery interface. See Declaring Capabilities for KeypadController Interface. Be sure to include a keys attribute and list the keystrokes that you support. Additionally, note that KeypadController requires Alexa Client Library version 1.4.5 or later. More details are provided in Alexa.Discovery.

Last updated: Oct 30, 2020