Your Alexa Dashboards
Sign In
?
Sign In
Your Alexa Dashboards Support

Skill Simulation API

The Skill Simulation API is an asynchronous API that simulates a skill execution. A successful response will contain a header with the location of the simulation resource. In cases where requests to this API results in an error, the response will contain a description of the problem.

All SMAPI v1 APIs will throw the following error responses if appropriate: HTTP/1.1 429 TooManyRequestsException if a request is throttled, and HTTP/1.1 503 if a service is unavailable.

This feature is not supported for skills using the following locales.

  • en-AU
  • en-CA
  • en-IN
  • ja-JP

You can use this API to simulate those skills for which you are the developer. The skill being simulated must be enabled on your account and must be in the development stage. This API does not support concurrent requests per user.

The Skill Simulation API must be used only for skill testing purposes.

See also: Alexa Skills Kit Command Line Interface and Alexa Skill Management API Overview and Skill Invocation API

Skill Simulation API Request

HTTP method and path

POST /skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/simulations

Request

Request Headers

Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string

Request Body

{
  "input": {
    "content": "ask greeter to say hello"
  },
  "device": {
    "locale": "en-US"
  }
}

Request Attributes Definition

Attribute Description
contentString corresponding to the utterance text of what a customer would say to Alexa
localeValid locale, such as en-US, for the virtual device used in the simulation

Skill Simulation API Response

Response Headers

Content-Type: application/json
Location: /skills/{skillId}/simulations/{simulationId}
X-Amzn-RequestId: string

Response Body

200 OK

{
  "id": string,
  "status": "IN_PROGRESS",
  "result": null
}

Errors

Error Response Body

{
  "message": string
}
Attribute Description
codeError code that maps to an error message. Developers with different locales should be able to lookup the error description based on this code.
messageA human-readable description of the error

Error Codes in Response

Response Description
400 Bad Request Invalid or missing data.
403 Forbidden API user does not have permission to call this API or is currently in a state that does not allow simulation of this skill.
404 Not Found The specified skill does not exist.
409 Conflict A request is currently being processed for this developer. Developer attempted to make concurrent Simulate Skill requests.

Sample Skill Simulation Request (POST)

HTTP Method and Path

POST /skills/34b178945-6ec3-1749-a123-3cbd123456ab/simulations

Request Headers

Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json

Request Body

{
  "input": {
    "content": "ask greeter to say hello"
  },
  "device": {
    "locale": "en-US"
  }
}

Sample Skill Simulation Response (200 OK) - Successful

This response represents a successful response to an intent request.

Response Headers

HTTP 200 OK

Location: /skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/simulations/34b178945-6ec3-1749-a123-3cbd123456ab
X-Amzn-RequestId: c03faf54-684d-11e7-6249-6bbd1825c634

Response Body

{
  "id": "34b178945-6ec3-1749-a123-3cbd123456ab",
  "status": "IN_PROGRESS",
  "result": null
}

Skill Simulation Request (GET)

HTTP Method and Path

GET /skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/simulations/34b178945-6ec3-1749-a123-3cbd123456ab

Request Headers

Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json

Request Body

No request body for GET requests.

Skill Simulation Response (200 OK) for GET request

Response Headers

Content-Type: application/json
X-Amzn-RequestId: string

Response Body

{
  "id": string,
  "status": string enum["IN_PROGRESS", "SUCCESSFUL", "FAILED"],
  "result": {
    "skillExecutionInfo": {
      "invocationRequest": {
        "endpoint": string,
        "body": object
      },
      "invocationResponse": {
        "body": object
      },
      "metrics": {
        "skillExecutionTimeInMilliseconds": integer
      }
    },
    "error": {
      "message": string
    }
  }
}
Attribute Description
idId of simulation.
statusCurrent status of the simulationm either IN_PROGRESS, SUCCESSFUL, or FAILED.
invocationRequest.endpointSkill’s AWS Lambda or HTTPS endpoint
invocationRequest.bodyJSON payload that was sent to the skill’s AWS Lambda or HTTPS endpoint
invocationResponse.bodyPayload that was returned by the skill’s AWS Lambda or HTTPS endpoint.
skillExecutionTimeInMillisecondsHow long, in milliseconds, it took the skill’s AWS Lambda or HTTPS endpoint to process the request.

Sample Skill Simulation Request (GET)

HTTP Method and Path

POST /skills/amzn1.ask.skill.1234.../simulations

Request Headers

Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string

Request Body

{
  "input": {
    "content": "ask greeter to say hello"
  },
  "device": {
    "locale": "en-US"
  }
}

Sample Skill Simulation Response (200 OK) - Successful

This response represents a successful response to an intent request.

Response Headers

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: string

Response Body

{
  "id": "34b178945-6ec3-1749-a123-3cbd123456ab",
  "status": "SUCCESSFUL",
  "result": {
    "skillExecutionInfo": {
      "invocationRequest": {
        "endpoint": "arn:aws:lambda:us-east-1:123456789:function:HelloWorld",
        "body": {
          "version": "1.0",
          "session": {
            "new": true,
            "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
            "application": {
              "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
            },
            "attributes": {},
            "user": {
              "userId": "amzn1.ask.account.12345ABCDEFGH"
            }
          },
          "context": {
            "System": {
              "application": {
                "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
              },
              "user": {
                "userId": "amzn1.ask.account.12345ABCDEFGH"
              }
            }
          },
          "request": {
            "type": "IntentRequest",
            "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
            "timestamp": "2017-08-14T04:20:20Z",
            "locale": "en-US",
            "intent": {
              "name": "SayHello"
            }
          }
        }
      },
      "invocationResponse": {
        "body": {
          "version": "1.0",
          "sessionAttributes": {},
          "response": {
            "outputSpeech": {
              "type": "PlainText",
              "text": "hello, world"
            },
            "shouldEndSession": true
          }
        }
      },
      "metrics": {
        "skillExecutionTimeInMilliseconds": 100
      }
    },
    "error": null
  }
}

Sample Skill Simulation Response (200 OK) - In Progress

Response Headers

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: string

Response Body

{
  "id": 34b178945-6ec3-1749-a123-3cbd123456ab,
  "status": "IN_PROGRESS",
  "result": null
}

Sample Skill Simulation Response (200 OK) - Failed

This response occurs when no skill simulation is allowed.

Response Headers

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: string

Response Body

{
  "id": "34b178945-6ec3-1749-a123-3cbd123456ab",
  "status": "FAILED",
  "result": {
    "skillExecutionInfo": null,
    "error": {
      "message": "Skill is currently disabled in development stage. Please enable skill in order to call this API."
    }
  }
}