How to Test an Echo Button Skill

As you develop your Echo Button skill, you have the following options for testing it:

  • End to end – You can test your skill using an Amazon Echo device and Echo Buttons that you own.
  • Alexa Simulator – You can test your skill without an Echo device, Echo Buttons, or any device by using the Alexa Simulator in the developer console. The simulator includes simulated Echo Buttons that you can press and that light up in an approximation of the animations that your skill sends to the buttons.
  • AWS Lambda console – If your skill code is in AWS Lambda, you can use the AWS Lambda console to invoke your skill and examine the JSON response.
  • Command line – By using the Alexa Skills Kit Command-Line Interface (ASK CLI), you can send a JSON request to your skill, regardless of where the code is hosted, and examine the JSON response.

For a list of tests specific to Echo Button skills, see Echo Button Skill Functional Tests.

For general information about testing custom skills, see Test and Debug a Custom Skill.

End-to-End Testing

To test your Echo Button skill with an Echo device and Echo Buttons, take the steps described next. You can also enable beta testers to test your skill. For more information, see Skill Beta Testing for Alexa Skills.

Step 1: Register Your Echo Device to your Developer Account

To test with an Amazon Echo device and Echo Buttons, the Echo device must be registered to the email address that you used to sign up for your developer account on the developer console. If you already set up your device using an account other than your Amazon developer account, follow these steps:

  1. Go to the web version of the Amazon Alexa app ( and sign in with your Amazon developer account.
  2. Follow the on-screen instructions to re-register your device with your developer account. This will unregister the existing email address.
  3. If you want to re-add a non-developer account as a user of the device, you can do so by using the Household feature.

Step 2: Enable Your Skill in the Alexa App

Skills that are in development status are available to you to test. To enable your skill, do the following:

  1. Go to the web version of the Alexa app ( and sign in with your Amazon developer account.
  2. Choose Skills from the main menu.
  3. In the upper right, choose Your Skills.
  4. Scroll down the list of skills that are associated with your account, and select the skill that you want to test.
  5. On the detail page of your skill, choose Enable.

Step 3: Invoke Your Skill

Invoke your skill with a voice request, just as a user would.

Alexa Simulator

You can test your Echo Button skill without physical Echo Buttons by using the Alexa Simulator. The simulator enables you to interact with your Echo Button skill by using text, voice, and simulated Echo Buttons. The simulator maintains the skill session just as an Echo device would, so that you can test the dialog flow. The simulated Echo Buttons light up in an approximation of the animations that your skill sends to the buttons. The simulator also sends any cards that your skill returns to the Alexa app the same way an Echo device would, and shows an approximation of how your skill's images display on the Echo Show and Echo Spot. For general information about the simulator, see Test Your Skill in the Developer Console.

The simulator only displays the Echo Buttons (Beta) option if your skill includes either the Game Engine interface, the Gadget Controller interface, or both. For information on how to add these interfaces to your skill, see Interfaces.

The following is a screenshot of the simulator with Echo Buttons:

Echo Buttons in the Alexa Simulator

To use the simulator with an Echo Button skill, do the following:

  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. At the top of the page, select Test.
  4. In the upper left, ensure that Test is enabled for this skill is selected.
  5. At the top right, next to Device Log, select Echo Buttons (Beta). If you don't see this option, then the skill does not include the Game Engine or Gadget Controller interface. (It must include at least one of those interfaces.)
  6. On the left, use the field that says Type or click and hold the mic to invoke your skill by typing or saying the invocation phrase without preceding the command with "Alexa". For example, if your skill is based on the Echo Buttons Trivia Game Template, type or say "open button trivia".
  7. Use voice, text, and press the simulated Echo Buttons to interact with your skill as you normally would.


Echo Button support in the simulator is currently in beta. The following limitations apply:

  • Skill I/O is available for simulated voice requests and launch requests only.
  • Echo Button colors in the simulator might not match the colors rendered on physical Echo Buttons. We recommend that you test colors on physical Echo Buttons before publishing your skill.

AWS Lambda Console

You can test your Lambda function by sending it requests from the AWS Lambda console. You can provide a custom JSON request, or you can select a predefined Alexa skill request. The following procedure shows how to send your skill a launch request.

Step 1: Find Your Skill in the AWS Lambda Console

To find your skill in the AWS Lambda console, take the following steps:

  1. Sign in to the AWS Management Console and navigate to the AWS Lambda console, which is located under Compute services.
  2. Using the region selector at the top right of the page, select the region that contains the Lambda function that provides the endpoint for your skill. For a list of regions that the Alexa Skills Kit supports for the Lambda endpoint, see Provide Multiple Endpoints for Your Skill.
  3. Navigate to the Lambda function that provides the endpoint for your skill.

Step 2: Configure a Test Event

Now you create a test event based on a template that contains a JSON request that invokes your skill. Continuing from the previous step:

  1. At the top right of your Lambda function's page, from the Select a test event dropdown menu, select Configure test events.
  2. In the Configure test event dialog box, select Create new test event.
  3. For Event template, search for Alexa.
  4. Select Alexa Start Session.
  5. For Event name, enter AlexaStartSession.
  6. At the bottom of the dialog box, select Create.

Step 3: Run the Test

Now you can trigger the test event that you created. Continuing from the previous step:

  1. At the top right of your Lambda function's page, from the dropdown menu next to Test, select AlexaStartSession, which you created in the last step.
  2. Select Test. The Execution Result displays whether the test succeeded or failed.
  3. Under Execution Result, select Details to examine the response that your function provided.

Command Line

To test individual requests and responses using the ASK CLI, take the following steps.

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

To test the skill using the ASK CLI, 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: Review the Interaction Model

The JSON request that you will send to your skill must include an intent. You can review the intents that your skill supports as follows:

  1. Download the interaction model to a file called model.json by typing the following subcommand, where locale can be en-US, en-GB or de-DE:
    ask api get-model –s {skill_id} -l {locale} > model.json
  2. Open the file and review the intents array to find an intent.

Step 4: Assemble a Request

You now need to create a text file that contains the JSON request to send to your skill. For the request format, see Request and Response JSON Reference.

The following is an example of a simple request. Replace the instances of REPLACE-WITH-SKILL-ID with the skill ID you found in a previous step, and replace REPLACE-WITH-INTENT with an intent from the interaction model.

  "session": {
    "new": true,
    "sessionId": "SessionId.12345678910",
    "application": {
      "applicationId": "REPLACE-WITH-SKILL-ID"
    "attributes": {},
    "user": {
      "userId": "amzn1.ask.account.12345678910"
  "request": {
    "type": "IntentRequest",
    "requestId": "RequestId.12345678910",
    "intent": {
      "name": "REPLACE-WITH-INTENT",
      "slots": {}
    "locale": "en-US",
    "timestamp": "2017-10-13T00:11:37Z"
  "context": {
    "System": {
      "application": {
        "applicationId": "REPLACE-WITH-SKILL-ID"
      "user": {
        "userId": "amzn1.ask.account.12345678910"
      "device": {
        "supportedInterfaces": {}
  "version": "1.0"

Step 5: Send the Request

To send the request to your skill, take the following steps:

  1. Type the following subcommand, using the file and skill ID that you have from earlier steps. For region, specify the region of your Lambda function endpoint. Examples are NA and EU.
    ask api invoke-skill -f <json request file> -s <skill ID> -e <region>
  2. Examine the response. If the operation was successful, the response will include an invocationResponse object.

Next Steps