About Alexa Web API for Games

With Alexa Web API for Games, build rich and immersive voice-enabled games by using a combination of Alexa Skills Kit directives and familiar web technologies. For example, JavaScript, HTML5, CSS, and Web Audio. With these technologies, you can build Alexa games with custom animations or turn existing HTML games into multimodal gaming experiences that run on Alexa-enabled devices, such as the Echo Show and Fire TV.

The following diagram shows a user starting a voice-enabled game on an Alexa-enabled device.

Start a voice-enabled game on an Alexa-enabled device with a screen
  1. The user speaks to their device to start the game.
  2. The device sends the utterance to the Alexa service in cloud.
  3. The Alexa service processes the utterance by using automatic speech recognition, for conversion to text, and natural language understanding to recognize the intent of the text. Then, the Alexa service sends a request to your skill backend.
  4. Your skill gets the request showing the device supports HTML directives. The skill sends a response to start the web app, specifying the URL to where the web app is hosted.
  5. Alexa starts the browser on the device.
  6. The browser loads your game at the given URL. The browser sends multiple requests for each asset you include, just like a traditional web site.
  7. The customer interacts with the game by voice, touchscreen, and remote control. Your web app interacts with the skill backend for game logic, if any.

How users interact with the game

Users invoke and interact with your skill normally. Your skill starts the web app part of the experience in response to a standard request from the Alexa service. For example, you might design your skill to ask the user if they're ready to start the game:

User: Alexa, open My Web Game
Alexa: Welcome to My Web Game. Are you ready to begin?
User: Yes
Alexa: OK, starting the engines… (sound effects)
Skill launches the web app and displays the starting page.

After the web app starts, the user can interact with the app by using tap and voice, or remote and voice. For example, the user can:

  • Press buttons on the screen. These actions might trigger Alexa speech or other actions within your web app.
  • Speak commands to the game. For example, "Alexa, fire the missiles!"
  • Respond to voice prompts triggered by your app. For example, "That was a miss! Do you want to try again?"

This interaction continues until the web app closes. For example, when the user says, "Alexa, exit."

Build with the Alexa Web API for Games

To create a game with the Alexa Web API for Games, you build two parts:

As you plan and build your skill, you can build these pieces independently, and then add the integration. For example, you can create a fully functional web app for your game, and then add the calls for Alexa speech and voice control. You can design your game to include game logic in either the web app or in the skill backend.

Communication between your skill and your web app

Use the Alexa Web API for Games interfaces to communicate between your skill and your web app while the user interacts with your game.

  • The Alexa.Presentation.HTML interface provides your skill with directives and requests for communicating with the web app. Your skill uses directives to send information to the web app, and uses request handlers to listen for events coming from the web app.
  • The Alexa JavaScript API interface provides your web app with an Alexa class with methods and properties for communicating with the skill. Your web app calls methods on this class to send messages to the skill, and registers callbacks to listen for events coming from the skill.

The following diagram shows the communication flow.

Communication between your skill and your web app
  1. The user invokes your skill.
  2. The Alexa service processes the utterance and sends a LaunchRequest or IntentRequest.
  3. The request handler in your skill code returns a response with the Alexa.Presentation.HTML.Start directive. The response includes the URL of the web page to load onto the device and an optional speech response.
  4. The Alexa service directs the device to start the web app.
  5. The device launches your web app.
  6. The device displays the starting page.
  7. Your web app calls Alexa.create() to create an instance of the Alexa Client object.
  8. The user begins interacting with the web app normally.
  9. The web app calls alexa.skill.sendMessage() to send messages to the skill, such as an event that says that Alexa should prompt the user for voice input.
  10. alexa.skill.sendMessage() results in the Alexa.Presentation.HTML.Message request.
  11. The skill handles these incoming requests, and then responds with directives and output speech.
  12. The skill returns the Alexa.Presentation.HTML.HandleMessage directive to send messages to the app.
  13. The web app registers a callback to respond to incoming messages sent from the skill by using alexa.skill.onMessage().
  14. During this interaction, the skill session remains open until the user ends the game.

Other events, such as when Alexa begins and ends speech, are available to your web app to build the flow between on-screen events, such as button presses and voice commands. For examples about how you use communication between the skill and web app to build in voice control and Alexa speech responses, see Add Voice Control and Speech to the Web App.

Requirements for the skill and web app

To use the Alexa Web API for Games, your skill and your web app must meet the following requirements:

Supported devices

The following devices support Alexa Web API for Games. The Echo Show 10 is a motion-capable device.

Echo Family Devices

  • Echo Show (1st Gen)
  • Echo Show (2nd Gen)
  • Echo Show 5
  • Echo Show 8
  • Echo Show 10

Fire TV Devices

  • Fire TV Stick (2nd Gen)
  • Fire TV Stick 4K
  • Fire TV Stick (2020)
  • Fire TV (3rd Gen)
  • Fire TV Cube (1st Gen)
  • Fire TV Cube (2nd Gen)