Alexa Blogs
Today we released updates to the Smart Home Skill API that make it easier for you to support customer smart home experiences with Alexa. As a result, you are probably wondering how much effort it will take to update your smart home skill. The good news is that migrating existing functionality to the updated API is pretty easy, and you can ensure a seamless migration for existing customers.
Important Notes
When skills using the updated API are published for customer use, we will automatically migrate existing customer devices to use the updated API. Most devices will be migrated within the first 24 hours, but there are situations when the migration may be delayed, such as when a customer’s Echo is offline. To ensure your customers have a seamless experience, you’ll want to make sure you do the following two things:
- Support both version 2 and version 3 directives. Until a device is migrated, you will receive directives that use the existing message format (payload version 2); after a device is migrated, you will receive directives that use the updated message payload format (payload version 3). To properly handle commands during the migration period, your updated skill must be able to handle both existing (version 2) and updated (version 3) directives and message parsing.
- Maintain consistent device IDs. You should use the same device identifiers with the updated API that you used with the existing API. This avoids the creation of duplicate device records for your existing customers.
You can monitor message traffic using AWS Cloudwatch or your own logging and remove the version 2 directive handlers once you no longer see version 2 traffic.
How It Works
You will need to work with the development version of your skill and do the following:
- Choose payload version 3 for your skill in the Alexa developer portal. Your skill may receive both version 2 and version 3 messages as described above.
- Create a new development version of your AWS Lambda function. You should include your existing code, and add parsing and responses for the new message formats.
- Thoroughly test your skill with unit and functional testing to ensure your migrated code is working properly.
- Implement state reporting and proactive state updates. To learn more about implementing proactive state updates, review the documentation and join us for a live webinar early next month.
- Thoroughly test your state reporting and proactive state implementation.
- Resubmit your skill for certification. Your skill using the updated API will not be published until the new consumer experiences become available next month.
This blog will provide an overview of migrating your existing functionality and provide example messages, but you should check out the migration guide to get all of the details. And attend the live webinar to learn about asynchronous messages and proactive state updates.
Choose v3
To get started, in the developer portal, check the “v3” box on the Skill Information page to signal you are ready for your skill to receive v3 messages. (If your skill is live, click on “Go to Development.”) Next, you will make some changes to the skill’s AWS Lambda function (or create a new Lambda function) because the message formats are slightly different.
For existing functionality, the biggest conceptual differences are that appliances and devices are now called endpoints, and endpoints are described in terms of their capabilities instead of actions.
An endpoint has a broader definition than a device or appliance and can represent one of the following cloud-connected components:
- Physical device, such as a light, thermostat, or lock
- Virtual device, such as a scene
- Group or cluster of devices, such as a set of recessed ceiling lights controlled as a single light
- Software component, such as a web service
Capabilities replace actions to describe the types of requests to which a device can respond. Capability interfaces describe a set of endpoint functionality and the resulting directives your skill might receive and the response messages, the events, your skill can send in response. In addition, a capability interface describes the properties that an endpoint exposes. You choose the set of interfaces that best describe the functionality of your endpoint.
For example, PowerController and BrightnessController could be used to describe a device that supports being turned on and off and has a brightness setting, or ChannelController could be used to describe a video service that supports channel changes.
Update Your Lambda Function with the New Message Formats
To migrate your code, you need to decide what capabilities your skill supports and add code to handle them. The following table maps the actions used in the existing API to the Capability Interface used in the updated API.
Visit the linked interface topic for the list of directives, events, and properties associated with the interface.
| Operation |
Existing Actions |
New Capability Interface |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note that each endpoint should also include a new Alexa.EndpointHealth capability that informs Alexa about the health of that endpoint, such as whether the endpoint is reachable or not.
Understand the Message Format Changes
The message format has changed slightly. As mentioned previously, Alexa still sends directives to your skill, but you reply with an event. Directives and event formats are fairly similar and contain a header and a payload. Most directives and events specify an endpoint, and events can contain a context property. The contents of each of these varies depending on the type of directive or event. For example, following is a request to turn the power on for an endpoint. For details on the message format, see the Smart Home Skill API Message Reference and individual interface topics.
Here is an example of a v3 directive to turn on an endpoint:
{
"directive": {
"header": {
"namespace": "Alexa.PowerController",
"name": "TurnOn",
"payloadVersion": "3",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "some-access-token"
},
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {}
}
}
And following is an example of a successful response to the above “TurnOn” directive:
{
"context": {
"properties": [ {
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
} ]
},
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3",
"messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "Alexa-access-token"
},
"endpointId": "endpoint-001"
},
"payload": {}
}
}
Adopt the New Discovery Format
In addition to using capabilities to describe your endpoints, a few of the other fields in a v3 discovery response have changed. The following table list device fields and how they map between v2 and v3. You can learn more about device discovery in v3 in Alexa.Discovery.
| Purpose |
v2 field |
v3 field |
| Device identifier |
|
|
| Manufacture name |
|
|
| Name assigned by customer |
|
|
| Description of the device such as how it is connected |
|
|
| Map of string key/value pairs to store information about the device |
|
|
| Describe requests that a device can respond to |
|
|
| Device model name |
|
|
| Describes whether a device is currently reachable |
|
Superseded by |
Discovery Response Example
The following shows a simple discovery response for v3 that contains two endpoints with various capabilities:
{
"event":{
"header":{
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
"messageId":"0a58ace0-e6ab-47de-b6af-b600b5ab8a7a"
},
"payload":{
"endpoints":[
{
"endpointId":"endpoint-001",
"manufacturerName":"Sample Manufacturer",
"friendlyName":"Switch",
"description":"001 Switch that can only be turned on/off",
"displayCategories":[
"SWITCH"
],
"cookie":{
"detail1":"For simplicity, this is the only appliance",
"detail2":"that has some values in the additionalApplianceDetails"
},
"capabilities":[
{
"type":"AlexaInterface",
"interface":"Alexa.PowerController",
"version":"3",
"properties":{
"supported":[
{
"name":"powerState"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.EndpointHealth",
"version":"3",
"properties":{
"supported":[
{
"name":"connectivity"
}
],
"proactivelyReported":true,
"retrievable":true
}
}
]
},
{
"endpointId":"endpoint-002",
"manufacturerName":"Sample Manufacturer",
"friendlyName":"Light",
"description":"002 Light that is dimmable and can change color and color temperature",
"displayCategories":[
"LIGHT"
],
"cookie":{
},
"capabilities":[
{
"type":"AlexaInterface",
"interface":"Alexa.PowerController",
"version":"3",
"properties":{
"supported":[
{
"name":"powerState"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.ColorController",
"version":"3",
"properties":{
"supported":[
{
"name":"color"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.ColorTemperatureController",
"version":"3",
"properties":{
"supported":[
{
"name":"colorTemperatureInKelvin"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.BrightnessController",
"version":"3",
"properties":{
"supported":[
{
"name":"brightness"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.PowerLevelController",
"version":"3",
"properties":{
"supported":[
{
"name":"powerLevel"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.PercentageController",
"version":"3",
"properties":{
"supported":[
{
"name":"percentage"
}
],
"proactivelyReported":true,
"retrievable":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.EndpointHealth",
"version":"3",
"properties":{
"supported":[
{
"name":"connectivity"
}
],
"proactivelyReported":true,
"retrievable":true
}
}
]
}
]
}
}
}
Test Existing Functionality and Implement Proactive State Updates
When you have finished adding the new discovery method and the updated message formats thoroughly test your skill with unit and functional testing to ensure your migrated code is working properly.
Your next step will be to implement asynchronous messages and proactive state updates by sending events to the Alexa Event Gateway. To learn more about implementing proactive state updates, read the documentation visit the join us for a live webinar early next month.
When all steps are complete, submit your revised skill for certification. Before you know it, your customers will be up and running with the new smart home experiences.
Get Started
- Learn about Smart home development with Alexa.
- Read the Smart Home Skill API documentation.
- To create a skill from scratch, see Steps to Create a Smart Home Skill.
- For detailed steps to migrate existing skills, read the How to Migrate Your Alexa Skill to the Updated Smart Home Skill API blog and the Smart Home Skill Migration Guide.
- Learn about sending events to the Alexa Event Gateway.
- Register to attend the Adding Proactive State Updates to Alexa Smart Home Skills webinar.
- To see additional code samples, visit the Alexa Smart Home repository on GitHub.
