Your Alexa Dashboards Settings

Build Smart Home Skills for Entertainment Devices

Smart home skills created for home entertainment/AV devices give customers voice access to their smart TV, cable boxes and other entertainment devices. For example, with the appropriately-configured smart home skill, a customer can say, “Alexa, increase the volume on the TV” and hear the volume increase on their TV.

This document provides a overview of the technical requirements as well as specific directives and error messages for smart home skills that target entertainment devices.

Get started

If this is your first time creating a smart home skill, you should review the existing documentation as a prerequisite to this document. You will need to be familiar how to create a smart home skill and write the code for a Lambda function that handles requests from the Smart Home Skill API. For more information see:

Skill implementation

The next sections provide details about implementing a smart home skill for entertainment devices.

Smart home skills for entertainment devices in the developer portal

When you create a skill for entertainment devices, you need to make sure you receive messages for the entertainment device control in the Smart Home Skill API. To do this, you will select payload version 3 in the developer portal when you create your skill.

For more information and detailed steps, see Steps to Create a Smart Home Skill.

Message Format

Alexa sends your skill a directive as a result of a customer request and you send back an event indicating the request was successful or an error message. Alexa can then respond appropriately to the customer. Entertainment device control in the leverages message formats defined by payload version 3 of the API. Each device for is an endpoint described by a list of interface capabilities in the discovery response. Each interface provides directives that are sent by Alexa to the skill and events that can be sent from the skill back to Alexa. An interface also defines reportable properties that you might send in a response event to describe the current state of the entertainment device. For example, for a device that can change channels, you would implement the the Alexa.Discovery interface and the Alexa.ChannelController interface, which defines channel as a reportable property.

Discovery for Entertainment Devices

When you describe devices, you will also describe the capabilities associated with each device, and properties that you support for each capability.

If your endpoint supports the PlaybackController interface, you must specify the operations the endpoint supports in a supportedOperations string array in your discovery response.

The following code example shows how you might describe an entertainment device. For more information on device discovery messages, see Alexa.Discovery.

Example Discovery Response for an Entertainment Device

{  
   "event":{  
      "header":{  
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "payload":{  
         "endpoints":[  
            {  
               "endpointId":"appliance-001",
               "friendlyName":"Living Room Entertainment System",
               "description":" Entertainment System by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories":[  
                  "TV"
               ],
               "cookie":{  
                  "extraDetail1":"optionalDetailForSkillAdapterToReferenceThisDevice",
                  "extraDetail2":"There can be multiple entries",
                  "extraDetail3":"but they should only be used for reference purposes",
                  "extraDetail4":"This is not a suitable place to maintain current device state"
               },
               "capabilities":[  
                  {  
                     "type":"AlexaInterface",
                     "interface":"Alexa.Speaker",
                     "version":"1.0",
                     "properties":{  
                        "supported":[  
                           {  
                              "name":"volume"
                           },
                           {  
                              "name":"muted"
                           }
                        ]
                     }
                  },
                  {  
                     "type":"AlexaInterface",
                     "interface":"Alexa.ChannelController",
                     "version":"1.0",
                     "properties":{  
                        "supported":[  
                           {  
                              "name":"channel"
                           }
                        ]
                     }
                  },
                  {  
                     "type":"AlexaInterface",
                     "interface":"Alexa.PlaybackController",
                     "version":"1.0",
                     "properties":{ },
                     "supportedOperations" : ["Play", "Pause", "Stop"] 
                   },
                  {  
                     "type":"AlexaInterface",
                     "interface":"Alexa.InputController",
                     "version":"1.0",
                     "properties":{  
                        "supported":[  
                           {  
                              "name":"input"
                           }
                        ]
                     }
                  }
               ]
            }
         ]
      }
   }
}

Interfaces for Entertainment Devices

To act on customer requests, you will need to parse Alexa request messages and compose Alexa.Response events to respond. If an error occurs, you will need to return the correct error message. Messages are defined in interfaces, which are organized by device capability. The interfaces that describe entertainment device capabilities are described in the following table.

Operation Capability Interface
Turn things on and off Alexa.PowerController
Change the channel on a device Alexa.ChannelController
Change the input of a playback device Alexa.InputController
Control the playback of device; fast forward, rewind and pause Alexa.PlaybackController
Change the volume in incremental steps Alexa.StepSpeaker
Change the volume to anywhere on a continuous range Alexa.Speaker
Indicate an error has occurred Alexa.ErrorResponse