Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

Understand Echo Button Skills

If your skill is a custom skill, you can add support for Echo Buttons by using the Echo Buttons Skill API. Echo Buttons are physical buttons that connect to compatible Amazon Echo devices over Bluetooth. You can create skills that illuminate the buttons and react to button presses, such as 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 Echo Buttons. If your skill needs a way for users to provide input quickly, consider using Echo Buttons.

How Your Skill Can Incorporate Echo Buttons

To build a skill that interacts with 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 Echo Buttons. 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.

Echo Button 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 Echo Button input independently. That is, your skill might receive Echo Button events separately from voice intent requests.

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

Echo Buttons Skill API

How Echo Button Skills Differ From Typical Custom Skills

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

  • Interfaces – Echo Button 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 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, a Echo Button skill must include a VUI for at least one of the three default languages for the countries where Echo Buttons 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.
  • 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 Echo Button 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!"

Get Started

If you want to get started with sample code and learn the concepts later, see Echo Button Sample Code.

If you want to learn more about Echo Button skills, see the following topics:

Echo Button

How to set up an Echo Button skill

Specify Echo Button Skill Details

Echo Button

How to change the color of Echo Buttons

Light up Echo Buttons

Echo Button

How your skill gets input from Echo Buttons

Receive Echo Button Events
Define Echo Button Events

Echo Button

How your skill gets input from voice

Receive Voice Input

Echo Button

How your skill identifies Echo Buttons

Discover Echo Buttons

Echo Button

How to manage skill sessions and users

Keep the Session Open
Save the Skill State

Echo Button

Control whether new speech interrupts the speech that Alexa is currently saying

Control Interruption of Alexa's Speech

Echo Button

How to handle skill problems

Troubleshoot an Echo Button Skill
Handle Echo Button Skill Errors