Your Alexa Consoles
Sign In
?
Sign In
Support

Add Echo Buttons to an Existing Skill

This topic describes how to add Echo Button support to an existing custom skill. You can do this by using the developer console or by using the Alexa Skills Kit Command-Line Interface (ASK CLI).

If you want a sample of Echo Button skill code also, see Echo Button Sample Code.

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.

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:

Most Echo Button skills use both 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

First you must add the appropriate interfaces, as follows:

  1. Sign in to the Alexa Skills Kit developer console.
  2. Find your skill in the list. Under Actions for your skill, select Edit.
  3. On the left side, select Interfaces.
  4. 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.
  5. 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:

  1. In the developer console, at the top of the page, select Launch.
  2. 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.
  3. 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 Gadgets 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.

For the details of specific ASK CLI commands, see the ASK CLI Command Reference.

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:

  1. Type the following at a command prompt:
    ask api list-skills
  2. 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 Gadget 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:

ask api get-skill –s {skill_id} > skill.json

Step 4: Update the Skill Manifest

  1. Review Specify Echo Button Skill Details to see which fields you need to add to the skill manifest, depending on your use case. Echo Button skills typically use the configuration described in Skills That Receive Echo Button Input and Control Echo Buttons.
  2. Open skill.json with any text editor.
  3. Add the necessary gadget-related fields that you determined in a previous step and save the file.
  4. Type the following subcommand:
    ask api update-skill –s {skill_id} –f skill.json
  5. If you plan to publish the updated skill, you must resubmit it for certification.

Step 5: 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 Gadgets Skill API provides:

Step 6: Resubmit the Skill for Certification

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

Next Steps