Smart Home Skill v2-to-v3 Migration Guide

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 provides 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. Review the following information to understand the differences between v2 and v3, and changes you need to make to your skill to migrate 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.

• Steps to Build a Smart Home Skill that describes how to implement a v3 smart home skill.
• Alexa Interface Message and Property Reference that provides a general description of the v3 types of messages and the message format.
• List of Alexa Interfaces and Supported Languages for a list of interfaces by function.
• Alexa.Discover Interface 3 to see how you describe your devices and their capabilities in v3.
• Understand State and Change Reporting that 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 console

To switch your skill from v2 to v3, you choose Payload Version v3 in the Alexa developer console.

1. Sign in to the Alexa developer console.
2. Select the Development version of the skill.
3. 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.
4. 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 in the AWS console. You can create the function in the N Virginia (US) or Ireland (EU) region. For more details, see Implement Smart Home Skill Code.

Migrate your code to v3

Using your previous Lambda implementation as a guide, implement v3 functionality. You update your skill to parse the v3 directive format and compose Response events in the v3 format. For more details about how to parse and implement v3, see the Smart Home Interface Message Guide, interface topics and example code provided in Steps to Build a Smart Home Skill.

Support v3 discovery

You indicate that your skill supports v3 capability interfaces in your discovery response. For details, see Alexa.Discovery Interface 3.

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

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

The following examples show how to 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
          }
      }
  ]
}

Add v3 capability interfaces

Create implementations for the v3 capability interface directives that you choose. Update your skill to parse the request messages and compose event responses. 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.

The following table provides guidelines for the interfaces you should implement based on device capability and actions you have have identified in v2.

Support state reporting

Add code to respond to the ReportState directive with a StateReport event. For more details, see Understand State and Change Reporting.

Update your skill configuration

In the Alexa developer console, update your v3 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 because customers are 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:

1. 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.
2. Make sure that the skill works correctly.
3. 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.
4. Click Save.
5. 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.
6. When you verify your v3 Lambda correctly handles v2 directives, do discovery for the test account; either by voice or in the Alexa app.
7. 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. For more details, see Smart Home and Video Skills Certification Guide. If you have implementation 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 details, see Send Events to the Alexa Gateway.

Recertify your skill

After 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. For more details, see Works with Alexa Skill Requirements.

Related topics

• Steps to Build a Smart Home Skill
• Alexa Interface Message and Property Reference
• List of Alexa Interfaces and Supported Languages
• Alexa.Discover Interface 3

Last updated: Sep 25, 2025