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
orlive
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
Simulates a skill response given an example utterance.
Request
To simulate the skill, you make a POST
request.
Request header example
Request header parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Unique identifier of a skill. |
String |
Yes |
|
Stage of the skill. |
String |
Yes |
Request body example
Request body parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Object that contains information about the session behavior of the simulated dialog. |
Object |
No |
|
Value used to influence the session behavior of the simulated dialog.
|
String |
No |
|
Object that contains information about the input to the simulation. |
Object |
Yes |
|
The utterance from a user to Alexa. |
String |
Yes |
|
Object that contains information about the simulated Alexa-enabled device. |
Object |
Yes |
|
Locale for the virtual device used in the simulation. |
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 |
---|---|---|
|
Simulation ID that you can use in an API call to get the simulation result. |
String |
|
String that specifies the current status of the simulation. |
String |
|
Result of the skill simulation request. This value is |
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 |
---|---|
|
Skill simulation has successfully begun. The |
|
Invalid or missing data. |
|
The authentication token is invalid, expired, or doesn't have access to the resource. |
|
You don't have permission to call this API or you don't have permission to access this skill. |
|
The specified skill does not exist. |
|
A simulate skill request is currently being processed for you. You attempted to make concurrent requests. |
|
You exceeded the permitted request rate. |
|
Internal service error. |
|
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
Request header parameters
Parameter | Description | Type | Required |
---|---|---|---|
|
Unique identifier of skill. |
String |
Yes |
|
Stage of the skill. |
String |
Yes |
|
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 of the simulation. |
String |
|
Current status of the simulation. |
String |
|
Object that contains information about the simulation result. |
Object |
|
Object that contains the skill execution information. |
|
|
Object that contains the Alexa execution information. |
|
skillExecutionInfo object
Parameter | Description | Type |
---|---|---|
|
Array of objects that contains invocation information. |
Array of objects |
|
Object that contains invocation request information. |
Object |
|
Skill's AWS Lambda or HTTPS endpoint. |
String |
|
JSON payload that was sent to the skill's AWS Lambda or HTTPS endpoint. |
String |
|
Object that contains the invocation response information. |
Object |
|
Payload that was returned by the skill's AWS Lambda or HTTPS endpoint. |
String |
|
Object that contains information about the skill execution time. |
Object |
|
How long, in milliseconds, it took the skill's AWS Lambda or HTTPS endpoint to process the request. |
Integer |
alexaExecutionInfo object
Parameter | Description | Type |
---|---|---|
|
Array of responses from Alexa. |
Array of objects |
|
Type of response from Alexa. |
String |
|
Object that contains the content of the Alexa response. |
Object |
|
Textual representation of Alexa's speech response. |
String |
|
Array that contains at most five considered intents returned by natural language understanding (NLU). |
Array of |
consideredIntents object
Parameter | Description | Type |
---|---|---|
|
Name of the intent. |
String |
|
Enumeration that indicates whether the user explicitly confirmed or denied the entire intent. |
String |
|
Slot information. |
Object |
|
Slot name. |
Object |
|
Slot name. |
String |
|
Slot value. |
String |
|
Enumeration that indicates whether the user explicitly confirmed or denied this intent. |
String |
|
Object that represents the results of resolving the words captured from the user's utterance. |
Object |
|
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 |
|
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 |
|
Object that represents the status of entity resolution for the slot. |
Object |
|
Code that indicates the results of attempting to resolve the user utterance against the defined slot types. Valid values:
|
String |
|
Array of resolved values for the slot. |
Array |
|
Object that contains information about the resolved slot value. |
Object |
|
Resolved slot value. |
String |
|
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 |
---|---|
|
Successfully retrieved skill simulation information. |
|
The authentication token is invalid, expired, or doesn't have access to the resource. |
|
You don't have permission to call this API or you don't have permission to access this skill. |
|
The specified skill does not exist. |
|
You exceeded the permitted request rate. |
|
Internal service error. |
|
Service unavailable. |