Alexa.KeypadController Interface
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 in streaming apps. For more information about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.
For the list of languages that the KeypadController interface supports, see List of Alexa Interfaces and Supported Languages.
Utterances
When you use the Alexa.KeypadController interface, the voice interaction model is already built for you. After the customer says one of the following utterances, Alexa sends a corresponding directive to your skill.
The following examples show some customer utterances:
Alexa, scroll right.
Alexa, page down.
Alexa, go right.
Alexa, move down.
Alexa, select this.
Alexa, choose this.
Alexa, show details.
Alexa, show info.
Alexa, see more information.
Scenarios
Consider the following scenarios where you might use Alexa.KeypadController.
Voice-enable your home screen
If you are a manufacturer of a smart TV, you can use 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:
Alexa, turn on the TV.
Alexa, scroll right.
Alexa, launch [app].
Voice-enable your channel guide
If you are a live TV provider, you can use 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:
Alexa, turn on [name of live TV provider].
Alexa, go to cable guide.
Alexa, scroll down.
Alexa, select this.
Alexa, go home.
Voice-enable your app
If you are 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 also use voice to see more information about an onscreen element by opening the details page. 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:
Alexa, launch [app].
Alexa, show me comedies.
Alexa, scroll right.
Alexa, show me details.
Properties and Objects
The keystroke property
The Alexa.KeypadController interface uses the keystroke property as the primary property. The following are the valid values.
| 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's offscreen, or jump to a detail page. |
Discovery
You describe endpoints that support Alexa.KeypadController 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": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is 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": [
"INFO", "MORE", "SELECT",
"UP", "DOWN", "LEFT", "RIGHT",
"PAGE_UP", "PAGE_DOWN", "PAGE_LEFT", "PAGE_RIGHT"
]
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives
SendKeystroke directive
Support the SendKeystroke directive so that customers can scroll your content.
SendKeystroke directive payload details
| Field | Description | Type |
|---|---|---|
keystroke |
The keystroke requested by the user. | String |
SendKeystroke directive example
The following example illustrates a SendKeystroke directive that Alexa sends to your skill.
{
"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"
}
}
}
SendKeystroke response event
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.
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": {}
}
}
SendKeystroke directive error handling
If you can't handle a SendKeystroke directive successfully, respond with an Alexa.ErrorResponse event.
