Skill Simulation API
The Skill Simulation API enables skill developers to simulate a skill. You can test your skill and see the intent that a simulated device returns from your interaction model. In the API, the Intent Debugging returns the consideredIntents
returned in the JSON response and shows the intents that were considered and discarded. 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. You can also use the Utterance Profiler API to test specific utterances and use the responses to improve your interaction model.
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.
The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization
header whose value should be the access token retrieved from Login with Amazon.
All SMAPI v2 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.
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
or live
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
- Skill Simulation API Response
- Response Headers
- Response Body
- Errors
- Sample Skill Simulation Request (POST)
- Sample Skill Simulation Response (200 OK) - Successful
- Skill Simulation Request (GET)
- Skill Simulation Response (200 OK) for GET request
- Sample Skill Simulation Request (POST)
- Sample Skill Simulation Response (200 OK) - Successful
- Sample Skill Simulation Response (200 OK) - In Progress
- Sample Skill Simulation Response (200 OK) - Failed
Skill Simulation API Request
HTTP method and path
POST /v2/skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/stages/live/simulations
Parameters
Field | Description | Parameter Type | Required? |
---|---|---|---|
skillId | Unique identifier of skill. | Path | Yes |
stage | Stage of the skill. Accepted values are development and live (case sensitive). |
Path | Yes |
Request
Request Headers
Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json
Request Body
{
"session": {
"mode": string enum ["DEFAULT", "FORCE_NEW_SESSION"]
},
"input": {
"content": string
},
"device": {
"locale": string
}
}
Request Attributes Definition
Attribute | Description |
---|---|
session.mode
|
Optional. A value used to influence the session behavior of the simulated dialog. Session mode can be either FORCE_NEW_SESSION , which ensures that a new dialog session is started before running the simulation, or DEFAULT , which keeps the default session behavior of the simulated dialog.
|
input.content
|
String corresponding to the utterance text of what a customer would say to Alexa |
device.locale
| Locale for the virtual device used in the simulation. Valid locales include: en-US , en-GB , en-CA , en-AU , de-DE , fr-FR , en-IN , ja-JP
|
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 |
---|---|
message | A human-readable description of the error |
Error Codes in Response
Response | Description |
---|---|
400 Bad Request | Invalid or missing data. |
401 Not Authorized | The auth token is invalid/expired or doesn't have access to the resource. |
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. |
429 Throttling | API user has exceeded the permitted request rate. |
503 Service Unavailable | Service Unavailable. |
Sample Skill Simulation Request (POST)
HTTP Method and Path
POST /v2/skills/34b178945-6ec3-1749-a123-3cbd123456ab/stages/live/simulations
Request Headers
Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json
Request Body
{
"session": {
"mode": "FORCE_NEW_SESSION"
},
"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 /v2/skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/stages/live/simulations/34b178945-6ec3-1749-a123-3cbd123456ab
Field | Description | Parameter Type | Required? |
---|---|---|---|
skillId | Unique identifier of skill. | Path | Yes |
stage | Stage of the skill. Accepted values are development and live (case sensitive). |
Path | Yes |
simulationId | Identifer for the simulation | Yes |
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": {
"invocations": [{
"invocationRequest": {
"endpoint": string,
"body": object
},
"invocationResponse": {
"body": object
},
"metrics": {
"skillExecutionTimeInMilliseconds": integer
}
}]
},
"alexaExecutionInfo": {
"alexaResponses": [{
"type": "Speech",
"content": {
"caption": string
}
}],
"consideredIntents": [{
"name": string,
"confirmationStatus": string enum["NONE", "CONFIRMED", "DENIED"],
"slots": {
"SlotName": {
"name": string,
"value": string,
"confirmationStatus": string,
"resolutions": {
"resolutionsPerAuthority": [{
"authority": string,
"status": {
"code": string enum["ER_SUCCESS_MATCH", "ER_SUCCESS_NO_MATCH", "ER_ERROR_TIMEOUT", "ER_ERROR_EXCEPTION"]
},
"values": [{
"value": {
"name": string,
"id": string
}
}]
}]
}
}
}
}]
},
"error": {
"message": string
}
}
}
Attribute | Description |
---|---|
id | Id of simulation. |
status | Current status of the simulation. One of: IN_PROGRESS , SUCCESSFUL , or FAILED .
|
result
| Object that contains information about the simulation result. |
result.skillExecutionInfo
| Object that contains the skill execution information. |
result.skillExecutionInfo.invocations.invocationRequest
| Object that contains the invocation request information. |
result.skillExecutionInfo.invocations.invocationRequest.endpoint | Skill's AWS Lambda or HTTPS endpoint |
result.skillExecutionInfo.invocations.invocationRequest.body | JSON payload that was sent to the skill's AWS Lambda or HTTPS endpoint |
result.skillExecutionInfo.invocations.invocationResponse
| Object that contains the invocation response information. |
result.skillExecutionInfo.invocations.invocationResponse.body | Payload that was returned by the skill's AWS Lambda or HTTPS endpoint. |
result.skillExecutionInfo.invocations.metrics | Object that contains information about the skill execution time. |
result.skillExecutionInfo.invocations.metrics.skillExecutionTimeInMilliseconds | How long, in milliseconds, it took the skill's AWS Lambda or HTTPS endpoint to process the request. |
result.alexaExecutionInfo
| Object that contains the Alexa execution information. |
result.alexaExecutionInfo.alexaResponses.type
| Type of response from Alexa. Only Speech response type is currently supported.
|
result.alexaExecutionInfo.alexaResponses.content
|
Object that contains the content of the Alexa response. |
result.alexaExecutionInfo.alexaResponses.content.caption
|
Textual representation of Alexa's speech response. |
result.alexaExecutionInfo.consideredIntents
| An array contains at most 5 considered intents returned by natural language understanding (NLU). |
Sample Skill Simulation Request (POST)
HTTP Method and Path
POST /v2/skills/amzn1.ask.skill.1234../stages/live/simulations
Request Headers
Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json
Request Body
{
"session": {
"mode": "DEFAULT"
},
"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
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": {
"alexaExecutionInfo": null,
"skillExecutionInfo": null,
"error": {
"message": "Skill is currently disabled in development stage. Please enable skill in order to call this API."
}
}
}