Add Echo Buttons to an Existing Skill

Important: The Gadgets Skill API is now the Echo Buttons Skill API. The interface names and underlying functionality are unchanged. The Echo Buttons Skill API is in beta and is subject to change at any time without notice. We welcome your feedback.

Important Considerations

When you update a skill, you update the skill details, the skill code, or both. The skill details are aspects such as the interaction model, the publishing information, the interfaces that your skill supports, and so on. The skill code is your AWS Lambda function or skill endpoint.

Before you update a skill, keep the following important points in mind:

Skill details – If your skill is live, any updates that you make to the skill details will apply to the development version of the skill. Each live skill automatically has a development version because you cannot change the configuration of the live version of a skill. If you plan to publish the updated skill, you must resubmit it for certification after the updates. If it passes certification, then it will replace the previous live version of the skill.

Code changes – When you update your skill code to support Echo Buttons, do not update the live code. This will disrupt the experience of users who are already using your skill, especially because they might not have Echo Buttons. Use a different Lambda function or endpoint for the updates instead.

Language and locale limitations – There are no language and locale limitations for skills where the use of Echo Buttons is optional. However, when you choose which languages and locales to support, note that Echo Buttons are available in US, UK, Ireland, Germany, and Austria only. You should therefore distribute your skill to at least one of the countries in that list.

If a skill requires the use of Echo Buttons, the skill can only be used in countries where Echo Buttons are available. In that case, the following rules apply:

You can distribute Echo Button skills to US, UK, Ireland, Germany, and Austria, because that is where Echo Buttons are currently sold.

Echo Button skills can include a voice user interface (VUI) for any language that the Alexa Skills Kit supports. This is so that customers who choose to change the default language of their Echo device can have a localized experience. However, at minimum, an Echo Button skill must include a VUI for at least one of the three default languages for the countries where Alexa Gadgets are available: English (US), English (UK), and/or German.

For example, you can include a VUI language model for English (US) and your skill can be distributed in the US. If you include VUI language models for English (US), English (GB), and French, you can distribute your Echo Button skill to the US and UK, and customers will be able to use your skill in English (US), English (GB), and French depending on their device’s language settings.

If you add the Gadget Controller or Game Engine interface to an existing skill that does not follow the rules above, the skill will fail certification.

Adding Echo Button Support

To add Echo Button support to your skill, you modify the skill details to include additional interfaces and additional publishing information. The way that you make these modifications depends on whether you use the developer console or the [Alexa Skills Kit Command-Line Interface ASK CLI to edit the skill. Both methods are described in subsequent sections.

Interfaces to Add

Echo Button skills include support for one or both of the following interfaces:

Publishing Information to Add

Echo Button skills require additional publishing information, which determines how the skills are described in the Alexa Skill Store. The publishing information that you must provide depends on whether you include support for the Gadget Controller interface, the Game Engine interface, or both.

If your skill supports the Game Engine interface, you must specify whether Echo Buttons are required or optional, the minimum and maximum number of Echo Buttons that the skill supports, and the minimum and maximum number of players that the skill supports. If your skill only supports the Gadget Controller interface, then the only field that you must specify is whether Echo Buttons are required or optional.

Using the Developer Console

To add Echo Button support to your skill using the developer console, take the following steps.

Step 1: Add Interfaces

Find your skill in the list. Under Actions for your skill, select Edit.

On the left side, select Interfaces.

In the Alexa Gadget row of the interface list, select Gadget Controller if you want to animate Echo Buttons, and Game Engine if you want to receive Echo Button input.

At the top of the page, select Save Interfaces, and then select Build Model.

Step 2: Update the Publishing Information

Next you must add publishing information that is specific to Echo Buttons. Continuing from the previous step:

In the developer console, at the top of the page, select Launch.

In the middle of the page, provide the following information:

Echo Button Use – Select Required or Optional.

Number of Echo Buttons – Select the minimum and maximum number of Echo Buttons that the skill supports. If the skill supports the Game Engine, you must choose values for these fields. If you choose the same value for the minimum and maximum, the Alexa Skill Store will show the matching value as the required number of Echo Buttons.

Number of Players – Select the minimum and maximum number of players that the skill supports. If there isn't a maximum, select No Limit. If the skill supports the Game Engine, this information is required. Otherwise, it is optional.

At the bottom of the page, select Save and continue.

Step 3: Update the Skill Code

Modify your skill code, which is hosted by AWS Lambda or another web service, to use the additional directives that the Echo Buttons Skill API provides:

Step 4: Resubmit the Skill for Certification

If you plan to publish the updated skill, you must resubmit it for certification.

Using the ASK CLI

To add Echo Button support to your skill by using the ASK CLI, you first find the skill ID of your skill, and then use the skill ID to retrieve the skill manifest. The skill manifest is the file that contains the details of your skill. You then add the necessary fields to the skill manifest and upload the skill manifest to the developer console. These steps are described next.

Step 1: Install and Initialize the ASK CLI

If you haven't already, install and initialize the ASK CLI. The easiest way to do this is by following the Quick Start instructions.

Step 2: Find the Skill ID

Before you can edit the skill using the ASK CLI, you need to download the skill's configuration to your computer. To download this information, you need the skill ID. You can find the skill ID as follows:

Type the following at a command prompt:ask api list-skills

Find the skill that you want in the list, and copy its skill ID.

Step 3: Get the Skill Manifest

Now that you have the skill ID, you can retrieve the skill manifest, which is the file that provides metadata associated with the skill. For your skill to support Echo Buttons, the skill manifest must include certain fields. For example, you need to specify which Echo Buttons Skill APIs that your skill will support. You also need to specify gadget-related publishing information associated with the skill.

To download the skill manifest to a file called skill.json, type the following subcommand, using the skill ID that you retrieved in the previous step: