Smart Home Skill Migration Guide

If you have already published a Smart Home Skill, you should update it to use the v3 message format. This enables you to take advantage of new features and provide the best experience for your customers. In addition, v3 is required for Works with Alexa certification.

You should make changes in the developer console and in your Lambda function code. This topic covers the differences between v2 and v3, and changes you need to make to your skill to migrate it to payload version 3.
It's important to note that if you complete this migration successfully, your existing customers will get access to new features without any action on their part.

What's new in smart home development?

Capabilities replace actions in discovery: Device functionality is described with more flexibility using Capability Interfaces instead of Actions in the device discovery process. For example, PowerController or BrightnessController could be used to describe a device that supports being turned on and off and has a brightness setting. For more information, see Alexa.Discovery and the interface topics we've provided.

Querying capability: Use the new capability design to identify the device properties that Alexa can query, enabling customers to check the current state of a device using Alexa or the Alexa app.

Updates pushed to the Alexa app through state reporting: v3 enables you to report the state of your smart device, and for those state changes to appear in the Alexa app. For example, when a light is turned on using a light switch, you can report this information to the Alexa cloud. Alexa caches this information, and a customer sees the light is on in the Alexa app. For more information, see State Reporting.

Flexibility between asynchronous and synchronous messaging: In v3, how you respond to directives is flexible; you can respond either synchronously or asynchronously depending on the device and the capabilities of your device cloud. Read about the kinds of responses you can provide in the State Reporting document.

While you work on your v3 solution, you can continue to update your existing Lambda function that targets v2 until v2 APIs are deprecated.

How do I get started?

Look at the documentation and tools provided and start building a Lambda function for v3.

Smart Home Skill Message Guide that provides a general description of the types of messages that are exchanged in v3, the message format and lists interfaces by function.

Alexa.Discovery to see how you describe your devices and their capabilities in v3

Steps to migrate your skill

Following are the steps you need to follow to update your skill from v2 to v3.

Select v3 in the Developer Portal

To switch your skill from v2 to v3, you need to choose Payload Versionv3 in the developer console. To do this:

In the developer console, select the Development version of the skill.

In the Payload version of the Build page, select v3. This signals Alexa to send v3 messages to your skill. Note that when you create a new skill, it will automatically target v3.

Optionally request permissions to send asynchronous and proactive events. To do this, select Send Alexa Events in the Permissions section. Note that you can opt-in to these permissions later if needed. See the Implement Asynchronous and State Reporting Functionality section for more details.

Create a new Lambda

Create a new Lambda function. You can create this in the N Virginia (US) or Ireland (EU) region.

Important: Do not modify the Lambda function for the v2 version of your skill as you need this Lambda to continue to handle and respond to v2 directives while you are transitioning to v3. This ensures a smooth customer experience.

Provide a discovery response that describes devices that implement v3 capability interfaces. See Alexa.Discovery for more information.

The following table lists device fields and how they map between v2 and v3 discovery responses.

Purpose

v2 field

v3 field

Device identifier

applianceId

endpointId

Manufacture name

manufacturerName

manufacturerName

Name assigned by customer

friendlyName

friendlyName

Description of the device such as now it is connected

friendlyDescription

description

Map of string key/value pairs to store information about the device

additionalApplianceDetails

cookie The cookie property expects the same key/value pair format as additionalApplianceDetails so you can copy entries over as-is.

Describe requests that a device can respond to

actions array

capabilities array

Device model name

modelName

None

Describes whether a device is currently reachable

isReachable

None

The format for capabilities is significantly different than v2 actions. Read Alexa.Discovery for more details. Note that for each interface, you will report the properties and their level of support, indicating whether you support asynchronous and proactive events.

Following are some examples of how you would represent the same device actions in v2 and v3 format.

Create implementations for the v3 capability interface directives that you choose. You will need to parse the request messages and compose event responses. The following table provides guidelines for the interfaces you should implement based on device capability and actions you have have identified in v2.

Repeat the capability implementation step until you have updated your Lambda function to handle v3 directives and send v3 events for all of your devices and capabilities.

Add code to respond to ReportState directive with a StateReport event. For more information see, State Reporting.

Update your skill configuration to specify the ARN number for your new Lambda function that adds support for v3.

Github resources and testing

You can use the resources provided in the GitHub repo to validate your messages and unit test your new Lambda function code.
The repo includes:

Schema for validating messages

Sample lambda

Sample messages for each interface type

Ensure smooth customer migration

After your updated skill is certified and moved to Live, your skill may continue to receive control directives in the v2 format. This is because for customers already using your v2 skill, the skill version for an endpoint only updates when a discovery request is run. Alexa sends a silent discovery directive approximately every 4 hours and for endpoints that support silent discovery, customers should be transitioned in about 24 hours. Other customers could take longer depending on their device configurations, and whether they support silent discovery.

As a result, your skill must be able to handle v2 and v3 directives. To do this, you should leave your v2 Lambda as-is, and in the v3 Lambda, include logic to redirect v2 directives to the v2 Lambda, or provide some other mechanism for handling v2 control requests.
To validate that your skill behaves correctly:

Create a test v2 skill and configure it to work with your v2 Lambda. Account-link a test customer account, and discover devices for the skill so it receives v2 directives.

Ensure the skill works correctly.

Update the skill to v3 and configure the v3 Lambda:

In the test skill, on the Skill Information page, update the skill to v3 by changing the Payload Version you select in the developer console.

Update the ARN for your skill to the v3 Lambda.

Click Save.

DO NOT DISCOVER DEVICES FOR THE TEST ACCOUNT. Make control and query requests to devices associated with the account. For example, "Alexa, turn on the light" or "Alexa, what is the hallway thermostat temperature?". You should see v2 directives in the AWS CloudWatch logs for your v3 Lambda. If your Lambda handles the v2 directives correctly, the test customer should be able to successfully control/query the devices. If these fail, then you are not handling v2 directives correctly in your v3 Lambda.

When you verify your v3 Lambda correctly handles v2 directives, do discovery for the test account; either by voice or in the Alexa app.

Now, make control and query requests again. You should see v3 directives in your in the CloudWatch logs for your v3 Lambda, and everything should work as expected.

If your v3 skill functions correctly for these migration tests, then you are ready to request certification. If you have issues, consult the developer forums or contact developer support.

Implement asynchronous and state reporting functionality

You are not required to send Alexa change reports, but it is recommended that you do.
To start the process, you must get the necessary permissions by selecting Send Alexa events in the developer console. Find this in the Permissions section of the Build page.

If needed, update your discovery response to indicate the level of support for each interface property. You can specify a property as proactiveReportable and/or retrievable.

Add code to your Lambda to handle the AcceptGrant message in the Alexa.Authorization interface. Use the authorization code provided to call Login with Amazon (LWA) to retrieve authorization and refresh tokens and store them for a customer. You will use the authorization tokens in messages to the Alexa event endpoint. For more details about the authentication process, see Authenticate a Customer to Alexa with Permissions.

Important: When a skill with permission to send Alexa events is certified, there is a backfill process that sends an AcceptGrant for every customer with your v2 skill enabled. Make sure that your system is ready for these messages and can successfully acquire and store authentication and refresh tokens for each customer.

Make sure you include the correct correlation tokens and a scope containing the customer access token in events you send to Alexa.

Add code to send ChangeReport events to the Alexa event gateway when an endpoint value changes for a reason other than an Alexa directive. For more information, see Send Events to the Alexa Event Gateway.

Recertification of your skill

When you have migrated all of your Lambda functionality to v3, and tested the new skill thoroughly (with v2 and v3 directives), you must submit your updated skill for certification.
In addition, if you previously certified a smart home device with a v2 skill as Works with Alexa, you will need complete the Works with Alexa certification process with your devices and the new v3 skill. See Works with Alexa Requirements for a Smart Home Skill for more information.