Alexa.InputController Interface
The Alexa.InputController interface describes messages for changing the input of an entertainment device.
For the list of locales that are supported for the InputController interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.InputController interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, change the input to DVD.
After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.
Discovery
When you send a discovery message for an endpoint that supports InputController, you specify the inputs it supports with an inputs array.
Each input in the array has the following fields.
| Property | Description | Type | Required |
|---|---|---|---|
name |
The name of the input. The name must be unique across inputs for this endpoint. Valid values are: AUX 1, AUX 2, AUX 3, AUX 4, AUX 5, AUX 6, AUX 7, BLURAY, CABLE, CD, COAX 1, COAX 2, COMPOSITE 1, DVD, GAME, HD RADIO, HDMI 1, HDMI 2, HDMI 3, HDMI 4, HDMI 5, HDMI 6, HDMI 7, HDMI 8, HDMI 9, HDMI 10, HDMI ARC, INPUT 1, INPUT 2, INPUT 3, INPUT 4, INPUT 5, INPUT 6, INPUT 7, INPUT 8, INPUT 9, INPUT 10, IPOD, LINE 1, LINE 2, LINE 3, LINE 4, LINE 5, LINE 6, LINE 7, MEDIA PLAYER, OPTICAL 1, OPTICAL 2, PHONO, PLAYSTATION, PLAYSTATION 3, PLAYSTATION 4, SATELLITE, SMARTCAST, TUNER, TV, USB DAC, VIDEO 1, VIDEO 2, VIDEO 3, XBOX. See also: Input. |
string | yes |
Example: Discover.Response with InputController
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
},
"payload": {
"endpoints": [
{
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InputController",
"version": "3",
"inputs": [
{
"name": "HDMI 1"
},
{
"name": "HDMI 2"
}
]
}
]
}
]
}
}
}
AddOrUpdateReport example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "00000000-0000-0000-0000-000000000000"
},
"payload": {
"endpoints": [
{
"endpointId": "appliance-001",
"friendlyName": "Entertainment System",
"description": "BrandName by Sample Manufacturer",
"manufacturerName": "Sample Manufacturer",
"displayCategories": [
"TV"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.Speaker",
"version": "3",
"properties": {
"supported": [
{
"name": "volume"
},
{
"name": "muted"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PlaybackController",
"version": "3",
"properties": {},
"supportedOperations": [
"Play",
"Pause",
"Stop"
],
"proactivelyReported": true,
"retrievable": true
},
{
"type": "AlexaInterface",
"interface": "Alexa.InputController",
"version": "3",
"inputs": [
{
"name": "HDMI1"
},
{
"name": "HDMI2"
}
],
"proactivelyReported": true,
"retrievable": true
},
{
"type": "AlexaInterface",
"interface": "Alexa.ChannelController",
"version": "3",
"properties": {
"supported": [
{
"name": "channel"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [
{
"name": "connectivity"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives
SelectInput
Request to change to the input or input device.
User: Alexa, change the input to input name
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.InputController",
"name": "SelectInput",
"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": {
"input": "HDMI 1"
}
}
}
Payload details
| Property | Description | Type | Required |
|---|---|---|---|
input |
The identifier for the input device the customer requested. | string | yes |
Events and Properties
For this capability, you must reply:
- Synchronously, which means you send a Response to Alexa from the Lambda function.
When you send a Response, you should include the state of the interface properties in the context of the message.
Properties
When the input state changes, send a state report containing an input property.
| Property Name | Property Type | Description |
|---|---|---|
input |
Input | String identifying the new input device. For example, HDMI 1. |
Response
Send an Response when you successfully handle a SelectInput directive.
Example Response
The following example shows an Alexa response.
{
"context": {
"properties": [
{
"namespace": "Alexa.InputController",
"name": "input",
"value": "HDMI 1",
"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": {}
}
}
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.
Additional Sample Code
See the sample request and response messages in the Alexa smart home GitHub repo:
