Developer Console

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.

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:

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.

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

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