Smart Home Skill v2-to-v3 Migration Guide

Note: Sign in to the developer console to build or publish your skill.

If you published a Smart Home Skill that uses the v2 message format, update it to use the v3 message format. This migration 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 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 Alexa. Alexa caches this information, and a customer sees the light is on in the Alexa app. For details, 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 Interface Message Guide that provides a general description of the v3 types of messages and the message format.
List of Alexa Interfaces for a list of interfaces by function.
Alexa.Discovery to see how you describe your devices and their capabilities in v3.
State Reporting topic, which describes the different ways and message formats to report the state of your device endpoints.
Request Access to the Alexa Event Gateway, which describes the permissions framework to for sending asynchronous responses to Alexa.
Send Events to the Alexa Event Gateway, which describes how to send Alexa events to Alexa.

Steps to migrate your skill

Complete the following steps to update your skill from v2 to v3.

Select v3 in the Developer Portal

To switch your skill from v2 to v3, choose Payload Version v3 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. For details, see Send Events to the Alexa Event Gateway section.

Create a new Lambda

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

Important: Don't modify the Lambda function for the v2 version of your skill as you need the v2 Lambda to continue to handle and respond to v2 directives while you transition your skill to v3.

Migrate your code to v3

Using your previous implementation as a guide, implement v3 functionality, which is, parse the v3 directive format and compose Response events in the v3 format. For more details on how to parse and implement v3, see the Smart Home Interface Message Guide, interface topics and example code provided in the Steps to Create a Smart Home Skill topic.

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.

Thermostat example

Thermostat Discovery Response - v2 Actions

{
    "actions": [
        "incrementTargetTemperature",
        "decrementTargetTemperature",
        "getTargetTemperature",
        "setTargetTemperature"
    ]
}

Thermostat Discovery Response - v3 Capabilities

The following code example shows a discovery response that indicates proactive events will be sent by specifying proactivelyReported and retrievable are true for the supported properties.

{
    "capabilities": [{
        "type": "AlexaInterface",
        "interface": "Alexa.ThermostatController",
        "version": "3",
        "properties": {
            "supported": [{
                    "name": "targetSetpoint"
                },
                {
                    "name": "lowerSetpoint"
                },
                {
                    "name": "upperSetpoint"
                },
                {
                    "name": "thermostatMode"
                }
            ],
            "proactivelyReported": true,
            "retrievable": true
        }
    }]
}

Light example

Light Discovery Response - v2 Actions

{
  "actions": [
      "turnOn",
      "turnOff",
      "setPercentage",
      "incrementPercentage",
      "decrementPercentage",
      "setColor",
      "setColorTemperature",
      "incrementColorTemperature",
      "decrementColorTemperature"
  ]
}

Light Discovery Response - v3 Capabilities

The following code example shows a discovery response that indicates proactive events will be sent by specifying proactivelyReported and retrievable are true for each property.

{
  "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
          }
      }
  ]
}

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.

Operation	Version 2 Actions	v3 Capability Interface
Turn things on and off	turnOn turnOff	Alexa.PowerController
Change a percentage value for a light	decrementPercentage incrementPercentage setPercentage	Alexa.BrightnessController
Change a generic percentage value	decrementPercentage incrementPercentage setPercentage	Alexa.PercentageController
Get or set a temperature	setTargetTemperature, incrementTargetTemperature, decrementTargetTemperature	Alexa.ThermostatController
Get the temperature of a device	getTemperatureReading, getTargetTemperature	Alexa.TemperatureSensor
Get or set the lock state of a device	getLockState, setLockState	Alexa.LockController
Change the color of a light	setColor	Alexa.ColorController
Change the color temperature for a light	decrementColorTemperature, incrementColorTemperature, setColorTemperature	Alexa.ColorTemperatureController
Activate or deactivate a scene	turnOn, turnOff	Alexa.SceneController
Retrieve a camera feed	turnOn, turnOff	Alexa.CameraStreamController

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.

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.
Make sure that 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, see Stack Overflow or contact developer support.

Implement asynchronous and state reporting functionality

You aren't required to send Alexa change reports, but it's 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 use the authorization tokens in messages to the Alexa event endpoint. For more details about the authentication process, see Request Access to the Alexa Event Gateway.

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 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.

Was this page helpful?

Provide feedback

Last updated: Nov 22, 2023