Skill Simulation API

The Skill Simulation API enables you to see the intent that a simulated Alexa-enabled device returns from your interaction model. You can use this information to determine how to use additional samples to train your model to resolve utterances to their intended intents and slots. This API must be used only for skill testing purposes.

The skill you simulate must meet the following requirements:

  • The skill must be a custom skill.
  • The skill must belong to the developer account that you use to call this API.
  • The skill must be enabled.
  • The skill must be in the development or live stage.

To test specific utterances and use the responses to improve your interaction model, use the Utterance Profiler API.

API endpoint

The API's endpoint is https://api.amazonalexa.com.

Authentication

Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.

Operations

The Skill Simulation API includes the following operations.

Operation HTTP method and URI

Simulate skill

POST /v2/skills/{skill-id}/stages/{stage}/simulations

Get simulation result

GET /v2/skills/{skill-id}/stages/{stage}/simulations/{simulation-id}

Simulate skill

Simulates a skill response given an example utterance.

Request

To simulate the skill, you make a POST request.

Request header example

Copied to clipboard.

POST /v2/skills/{skill-id}/stages/{stage}/simulations
Host: api.amazonalexa.com
Authorization: Bearer {access token}
Content-Type: application/json
Accept: application/json

Request header parameters

Parameter Description Type Required

skill-id

Unique identifier of a skill.

String

Yes

stage

Stage of the skill.
Valid values: development and live (case sensitive).

String

Yes

Request body example

Copied to clipboard.

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

Request body parameters

Parameter Description Type Required

session

Object that contains information about the session behavior of the simulated dialog.

Object

No

session.mode

Value used to influence the session behavior of the simulated dialog.
Valid values:

  • FORCE_NEW_SESSION: Ensures that a new dialog session is started before running the simulation.
  • DEFAULT: Keeps the default session behavior of the simulated dialog.

String

No

input

Object that contains information about the input to the simulation.

Object

Yes

input.content

The utterance from a user to Alexa.

String

Yes

device

Object that contains information about the simulated Alexa-enabled device.

Object

Yes

device.locale

Locale for the virtual device used in the simulation.
Valid values: en-US, en-GB, en-CA, en-AU, de-DE, fr-FR, en-IN, and ja-JP.

String

Yes

Response

On success, the response returns 200 OK and the Location header contains a path to the simulation. The response body contains the following parameters.

Response body example

{
  "id": "12345678-abcdefg",
  "status": "IN_PROGRESS",
  "result": null
}

Response body parameters

Parameter Description Type

id

Simulation ID that you can use in an API call to get the simulation result.

String

status

String that specifies the current status of the simulation.
Valid values: IN_PROGRESS, SUCCESSFUL, and FAILED.

String

result

Result of the skill simulation request. This value is null if the response code is 200 OK with a status of IN_PROGRESS. If the response code is 200 OK with a status of FAILED, the result contains an error.message field that contains a description of the error.

Object

HTTP status codes

The call to this API can return the following HTTP status codes. Error responses contain a message with a human-readable description of the error.

Status Description

200 OK

Skill simulation has successfully begun. The Location header contains a path to the simulation.

400 Bad Request

Invalid or missing data.

401 Not Authorized

The authentication token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

You don't have permission to call this API or you don't have permission to access this skill.

404 Not Found

The specified skill does not exist.

409 Conflict

A simulate skill request is currently being processed for you. You attempted to make concurrent requests.

429 Throttling

You exceeded the permitted request rate.

500 Internal Service Error

Internal service error.

503 Service Unavailable

Service Unavailable.

Get simulation result

Gets the result of a simulation that you ran using the simulate skill API.

Request

To get the results of a simulation, you make a GET request.

Request header example

Copied to clipboard.

GET /v2/skills/{skill-id}/stages/{stage}/simulations/{simulation-id}
Host: api.amazonalexa.com
Authorization: Bearer {access token}
Content-Type: application/json
Accept: application/json

Request header parameters

Parameter Description Type Required

skill-id

Unique identifier of skill.

String

Yes

stage

Stage of the skill.
Valid values: development and live (case sensitive).

String

Yes

simulation-id

Identifier for the simulation. You get this identifier from the simulate skill response.

String

Yes

Request body parameters

The request body is empty.

Response

On success, the response returns 200 Success and the response body contains the following properties.

Response body example

{
    "id": "12345678-abcdefg",
    "status": "IN_PROGRESS",
    "result": {
        "skillExecutionInfo": {
            "invocations": [{
                "invocationRequest": {
                    "endpoint": "example-endpoint",
                    "body": "JSON payload that was sent to the skill's endpoint"
                },
                "invocationResponse": {
                    "body": "Payload that was returned by the skill's AWS Lambda or HTTPS endpoint."
                },
                "metrics": {
                    "skillExecutionTimeInMilliseconds": 5
                }
            }]
        },
        "alexaExecutionInfo": {
            "alexaResponses": [{
                "type": "Speech",
                "content": {
                    "caption": "Example speech."
                }
            }],
            "consideredIntents": [{
                "name": "Intent name",
                "confirmationStatus": "CONFIRMED",
                "slots": {
                    "SlotName": {
                        "name": "Example slot name",
                        "value": "Example value",
                        "confirmationStatus": "CONFIRMED",
                        "resolutions": {
                            "resolutionsPerAuthority": [{
                                "authority": "",
                                "status": {
                                    "code": "ER_SUCCESS_MATCH"
                                },
                                "values": [{
                                    "value": {
                                        "name": "Example name",
                                        "id": "Example ID"
                                      }
                                }]
                            }]
                        }
                    }
                }
            }]
        },
        "error": {
            "message": "Error message"
        }
    }
}

Response body parameters

Parameter Description Type

id

ID of the simulation.

String

status

Current status of the simulation.
Valid values: IN_PROGRESS, SUCCESSFUL, or FAILED.

String

result

Object that contains information about the simulation result.

Object

result.skillExecutionInfo

Object that contains the skill execution information.

skillExecutionInfo object

result.alexaExecutionInfo

Object that contains the Alexa execution information.

alexaExecutionInfo object

skillExecutionInfo object
Parameter Description Type

skillExecutionInfo.invocations

Array of objects that contains invocation information.

Array of objects

skillExecutionInfo.invocations[i].invocationRequest

Object that contains invocation request information.

Object

skillExecutionInfo.invocations[i].invocationRequest.endpoint

Skill's AWS Lambda or HTTPS endpoint.

String

skillExecutionInfo.invocations[i].invocationRequest.body

JSON payload that was sent to the skill's AWS Lambda or HTTPS endpoint.

String

skillExecutionInfo.invocations[i].invocationResponse

Object that contains the invocation response information.

Object

skillExecutionInfo.invocations[i].invocationResponse.body

Payload that was returned by the skill's AWS Lambda or HTTPS endpoint.

String

skillExecutionInfo.invocations[i].metrics

Object that contains information about the skill execution time.

Object

skillExecutionInfo.invocations[i].metrics.skillExecutionTimeInMilliseconds

How long, in milliseconds, it took the skill's AWS Lambda or HTTPS endpoint to process the request.

Integer

alexaExecutionInfo object
Parameter Description Type

alexaExecutionInfo.alexaResponses

Array of responses from Alexa.

Array of objects

alexaExecutionInfo.alexaResponses[i].type

Type of response from Alexa.
Valid value: Speech.

String

alexaExecutionInfo.alexaResponses[i].content

Object that contains the content of the Alexa response.

Object

alexaExecutionInfo.alexaResponses[i].content.caption

Textual representation of Alexa's speech response.

String

alexaExecutionInfo.consideredIntents

Array that contains at most five considered intents returned by natural language understanding (NLU).

Array of consideredIntents objects

consideredIntents object
Parameter Description Type

consideredIntents[i].name

Name of the intent.

String

consideredIntents[i].confirmationStatus

Enumeration that indicates whether the user explicitly confirmed or denied the entire intent.
Valid values: NONE, CONFIRMED, or DENIED.

String

consideredIntents[i].slots

Slot information.

Object

consideredIntents[i].slotName

Slot name.

Object

consideredIntents[i].slotName.name

Slot name.

String

consideredIntents[i].slotName.value

Slot value.

String

consideredIntents[i].slotName.confirmationStatus

Enumeration that indicates whether the user explicitly confirmed or denied this intent.
Valid values: NONE, CONFIRMED, or DENIED.

String

consideredIntents[i].slotName.resolutions

Object that represents the results of resolving the words captured from the user's utterance.

Object

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority

Array of objects that represent each possible authority for entity resolution. An authority represents the source for the data provided for the slot. For a custom slot type, the authority is the slot type you defined.

Array of objects

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].authority

Name of the authority for the slot values. For custom slot types, this authority label incorporates your skill ID and the slot type name.

String

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].status

Object that represents the status of entity resolution for the slot.

Object

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].status.code

Code that indicates the results of attempting to resolve the user utterance against the defined slot types. Valid values:

  • ER_SUCCESS_MATCH: The spoken value matched a value or synonym explicitly defined in your custom slot type.
  • ER_SUCCESS_NO_MATCH: The spoken value did not match any values or
  • synonyms explicitly defined in your custom slot type.
  • ER_ERROR_TIMEOUT: An error occurred due to a timeout.
  • ER_ERROR_EXCEPTION: An error occurred due to an exception during processing.

String

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].values

Array of resolved values for the slot.

Array

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].values[i].value

Object that contains information about the resolved slot value.

Object

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].values[i].value.name

Resolved slot value.

String

consideredIntents[i].slotName.resolutions.resolutionsPerAuthority[i].values[i].value.id

Unique ID defined for the resolved slot value. This is based on the IDs defined in the slot type definition.

String

HTTP status codes

The call to this API can return the following HTTP status codes. Error responses contain a message with a human-readable description of the error.

Status Description

200 Success

Successfully retrieved skill simulation information.

401 Not Authorized

The authentication token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

You don't have permission to call this API or you don't have permission to access this skill.

404 Not Found

The specified skill does not exist.

429 Throttling

You exceeded the permitted request rate.

500 Internal Service Error

Internal service error.

503 Service Unavailable

Service unavailable.