Understand the Gadgets Skill API

The Gadgets Skill API enables you to build skills that control and receive input from Alexa Gadgets. An Alexa Gadget is an Alexa-connected accessory that interacts with compatible Amazon Echo devices.

The Gadgets Skill API currently supports one gadget type, Echo Buttons. Echo Buttons are physical buttons that connect to compatible Amazon Echo devices over Bluetooth. By using the Gadgets Skill API, you can create skills that illuminate the buttons and react to button presses. You can create first-to-respond games, multiple choice games, sequence puzzles, sound effect generators, and so on. Your skill does not need to be a game skill to use the Gadgets Skill API. If your skill needs a way for users to provide input quickly, consider using Echo Buttons.

How Your Skill Can Incorporate Gadgets

To build a skill that interacts with gadgets such as Echo Buttons, you create a custom skill and include support for one or both of the following interfaces:

  • The Gadget Controller interface enables skills to control gadgets. For example, your skill can use this interface to illuminate an Echo Button a different color.
  • The Game Engine interface filters button presses into named events that it forwards to your skill. Your skill configures the number and type of button presses that trigger each event. For example, you can configure the Game Engine to notify your skill after a user presses a button three times, instead of on every individual button press.

Gadget skills interact with Alexa using the same request-response mechanism and JSON formatting that other skills use, but your skill must take into account that Alexa processes voice input and gadget input independently. That is, your skill might receive gadget events separately from voice intent requests.

The following figure shows how voice input and gadget input interact with your skill.

Gadgets Skill API

How Gadget Skills Differ From Typical Custom Skills

The following is a summary of the main differences between typical custom skills and custom skills that support gadgets:

  • Interfaces – Gadget skills include support for the Gadget Controller interface, the Game Engine interface, or both. If you are building a skill for Echo Buttons, include support for both interfaces.

  • Language and locale limitations – There are no language and locale limitations for skills where the use of Alexa Gadgets is optional. However, when you choose which languages and locales to support, note that Alexa Gadgets 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 an Alexa Gadget, the skill can only be used in countries where Alexa Gadgets are available. In that case, the following rules apply:

    • You can distribute gadget skills to US, UK, Ireland, Germany, and Austria, because that is where Alexa Gadgets are currently sold.
    • Gadget 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, a gadget 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 gadget 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.
  • Input modes – Typical custom skills get user input through voice only. Gadgets such as Echo Buttons provide an additional mode of input. Gadget skills must be prepared to handle gadget input that occurs outside of a voice interaction, and keep track of any state information that needs to be shared between these two invocation modes.
  • Alexa Skill Store – Gadget skills have additional call-outs in the Alexa Skill Store. For example, if your skill won't work unless the user has Echo Buttons, it will be marked as Requires Echo Buttons. If your skill supports dual experiences (voice with or without Echo Buttons), it will be marked as Optional: Echo Buttons. The Alexa Skill Store will also list the minimum and maximum number of players that your skill supports, the minimum number of buttons that your skill requires, and the maximum number of buttons that your skill supports. You specify these attributes by using publishing information fields within the skill metadata.

Example Gadget Skill Flow

The following simple example demonstrates what happens behind the scenes when users interact with a skill that uses both voice and Echo Buttons. The scenario is two users playing a one-question trivia game.

User action Behind the scenes

A user says "Alexa, open Quick Trivia."

  • Alexa sends a launch request to the Quick Trivia skill.
  • The skill responds to Alexa. The response includes:
    • A speech directive for Alexa to say "Hello, players! Let's take a roll call. I'd like each of you to press your Echo Button."
    • A Game Engine directive to configure the game engine to notify the skill in 10 seconds and report which buttons were pressed in that timeframe.

Each user presses his or her Echo Button.

  • After 10 seconds, Alexa sends the skill an event in the form of a Game Engine request that provides the gadget ID of each button that was pressed at least once. The skill saves the gadget IDs for future reference.
  • The skill responds to Alexa. The response includes:
    • A Gadget Controller directive to animate the two identified buttons a sequence of bright colors.
    • A speech directive for Alexa to say "Ok, we have two players. Let's begin! The first player to buzz in gets to answer. The first question is: which planet is closest to the sun?"
    • A Game Engine directive that configures the game engine to notify the skill as soon as any button is pressed, and then stop sending further Echo Button input.

Player 2 presses her Echo Button.

  • Alexa sends the skill an event in the form of a Game Engine request that indicates that a button with the gadget ID corresponding to Player 2 was pressed.
  • The skill responds to Alexa. The response includes a speech directive for Alexa to say "Player 2, what is your answer?"

Player 2 answers "Mercury."

  • Alexa sends an intent request to the skill containing Player 2's answer.
  • The skill responds to Alexa. The response includes:
    • A speech directive for Alexa to say "That is correct! Player 2 wins! Great job, Player 2!"
    • A Gadget Controller directive to animate the light of Player 2's button in a colorful sequence.
    • A speech directive for Alexa to say "Would you like to play again?"

Player 1 says "No."

  • Alexa sends an intent request to the skill containing the player's response.
  • The skill responds to Alexa. The response includes a speech directive for Alexa to say "Ok. Thanks for playing!"

Next Steps