Alexa.KeypadController Interface 3

Implement the Alexa.KeypadController interface in your Alexa skill so that users can voice-control onscreen navigation. You can voice-enable scrolling, directional pad (d-pad), selection of onscreen elements, and showing more details for elements that have focus. You can enable voice navigation on your smart TV home screens, for live TV providers, or for streaming apps. For details about video skills, see Understand the Video Skill API. For the list of languages that the Alexa.KeypadController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.KeypadController interface uses the pre-built voice interaction model. After the customer says one of the following utterances, Alexa sends a corresponding directive to your skill. The following examples show some customer utterances:

Scenarios

Consider the following scenarios where you might use Alexa.KeypadController.

Voice-enable your home screen

If you’re a manufacturer of a smart TV, you can use Alexa.KeypadController to voice-enable the home screen. When the user views the list of apps that the TV supports, the user can use their voice to scroll right, left, up, or down, and to select the app of their choice. This scenario also uses the Alexa.PowerController and Alexa.Launcher interfaces. The following is an example of user utterances for this scenario:

English (All)

Voice-enable your channel guide

If you’re a live TV provider, you can use Alexa.KeypadController to voice-enable the channel guide. The user can use their voice to scroll up, down, right, or left through the guide, and to select a program. This scenario also uses the Alexa.PowerController and Alexa.Launcher interfaces. The following is an example of user utterances for this scenario:

English (All)

Voice-enable your app

If you’re an app developer, you might use Alexa.KeypadController to voice-enable your app to let the user use their voice to scroll up, down, right, or left. The user can use voice to see more information about an onscreen element by opening the details page, and to navigate back to the previous screen. This scenario also uses the Alexa.Launcher interface and the Alexa.RemoteVideoPlayer interface to display comedies. The following is an example of user utterances for this scenario:

English (All)

Reportable properties

The Alexa.KeypadController interface uses the keystroke property as the primary property. You identify that you support the properties in your discovery response. The following table shows the valid values for the keystroke property.

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 has focus. For example, show content that’s offscreen, or jump to a detail page.
Back button	`BACK`	Simulate the behavior of the back button on the remote control. For example, navigate back to the previous screen.

Discovery

You describe endpoints that support Alexa.KeypadController by using the standard discovery mechanism described in Alexa.Discovery. For the KeypadController interface, include a keys attribute and list the keystrokes that you support.

Discover response example

The following example shows a Discover.Response message for a device that supports the Alexa.KeypadController.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Description to be shown in the Alexa app",
          "friendlyName": "Device name, displayed in the Alexa app",
          "displayCategories": ["TV"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.KeypadController",
              "version": "3",
              "keys": [
                "BACK",
                "INFO", "MORE", "SELECT",
                "UP", "DOWN", "LEFT", "RIGHT",
                "PAGE_UP", "PAGE_DOWN", "PAGE_LEFT", "PAGE_RIGHT"
              ]
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.KeypadController interface directives to your skill.

SendKeystroke directive

Support the SendKeystroke directive so that customers can scroll your content.

SendKeystroke directive example

The following example shows a SendKeystroke directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.KeypadController",
      "name": "SendKeystroke",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint id",
      "cookie": {}
    },
    "payload": {
      "keystroke": "SELECT"
    }
  }
}

SendKeystroke directive payload

The following table shows the payload details for the SendKeystroke directive.

Property	Description	Type
`keystroke`	Keystroke requested by the user. For valid values, see `keystroke`.	String

SendKeystroke response

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. The following example shows a SendKeystroke response.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint id"
    },
    "payload": {}
  }
}

SendKeystroke directive error handling

If you can’t handle a SendKeystroke directive successfully and the error is specific to video, respond with an Alexa.Video.ErrorResponse event. For general errors, respond with a generic Alexa.ErrorResponse event. If the user requests a keystroke that your device doesn’t support, use the INVALID_VALUE error type.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Utterances

Scenarios

Voice-enable your home screen

Voice-enable your channel guide

Voice-enable your app

Reportable properties

Discovery

Discover response example

Directives

SendKeystroke directive

SendKeystroke directive example

SendKeystroke directive payload

SendKeystroke response

SendKeystroke directive error handling

​Utterances

​Scenarios

​Voice-enable your home screen

​Voice-enable your channel guide

​Voice-enable your app

​Reportable properties

​Discovery

​Discover response example

​Directives

​SendKeystroke directive

​SendKeystroke directive example

​SendKeystroke directive payload

​SendKeystroke response

​SendKeystroke directive error handling

​Related topics

Utterances

Scenarios

Voice-enable your home screen

Voice-enable your channel guide

Voice-enable your app

Reportable properties

Discovery

Discover response example

Directives

SendKeystroke directive

SendKeystroke directive example

SendKeystroke directive payload

SendKeystroke response

SendKeystroke directive error handling

Related topics