Utterance Profiler REST API Reference
Use the Utterance Profiler REST API to test user utterances and improve your skill's interaction model. The utterance profiler doesn't call an endpoint or invoke a skill. To test your skill's interaction model, you don't need the backend code for your skill.
With the Utterance Profiler API, you can see how utterances resolve to intents and slots in your interaction model. When an utterance doesn't resolve to the right intent or slot, you can update the interaction model and try again, all before writing any code for your skill. In the API response, you can see what intents Alexa considered and discarded. Then, you can 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 in the Alexa Skills Kit developer console. For details, see Test Your Utterances and Improve Your Interaction Model. To test the utterance with your skill, you can use the Alexa Simulator in the developer console or the Skill Simulation REST API.
API endpoint
The endpoint of the Utterance Profiler API 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 (LWA). For details, see Get an Access Token for SMAPI.
Operations
The Utterance Profiler API includes the following operations.
Operation | HTTP method and URI |
---|---|
|
Profile utterance
Profile an utterance against the most recent interaction model for your skill.
Request
To profile an utterance, you make a POST
request to the profileNlu
resource.
Request path and header example
POST /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/profileNlu
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
Path |
Locale of the interaction model to test. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"utterance": "i want to travel from seattle",
"multiTurnToken": null
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Utterance text to test. |
String |
Yes |
|
Opaque string that contains multi-turn related context. Include this field for multi-turn conversations only. Set the value to the token you received in the previous response. |
String |
No |
Response
A successful response returns HTTP 200 OK
, along with the utterance results.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The following example shows a response.
{
"sessionEnded": "false",
"selectedIntent": {
"name": "GetTravelTimeIntent",
"confirmationStatus": "CONFIRMED",
"slots": {
"DepartingCity": {
"name": "DepartingCity",
"value": "Seattle",
"confirmationStatus": "CONFIRMED",
"resolutions": {
"resolutionsPerAuthority": [{
"authority": "1234.City",
"status": {
"code": "ER_SUCCESS_MATCH"
},
"values": [{
"name": "Seattle",
"id": "1234"
}]
}]
}
},
"ArrivingCity": {
"name": "ArrivingCity",
"value": null,
"confirmationStatus": "NONE",
"resolutions": null
}
}
},
"consideredIntents": [{
"name": "GetTravelTimeIntent",
"confirmationStatus": "NONE",
"slots": {
"DepartingCity": {
"name": "DepartingCity",
"value": null,
"confirmationStatus": "NONE",
"resolutions": null
},
"ArrivingCity": {
"name": "ArrivingCity",
"value": null,
"confirmationStatus": "NONE",
"resolutions": null
}
}
}],
"multiTurn": {
"dialogAct": {
"type": "SlotValueConfirmation",
"targetSlot": "DepartureCity"
},
"token": "abcd1234...",
"prompt": "You want to start from Seattle, right?"
}
}
Response body properties
Property | Description | Type |
---|---|---|
|
Indicates whether the utterance caused Alexa to exit the skill. |
Boolean |
|
Intent that Alexa selected for the utterance. |
Intent object |
|
List of intents that Alexa considered, but didn't select. |
Array of Intent objects |
|
Included when the selected intent has dialog defined and the dialog is not completed. To continue the dialog, provide the value of the |
Object |
|
Prompts to the user. |
Object |
|
Dialog action for the next response from the user in this multi-turn dialog. For more details, see Dialog directives. |
String |
|
Target slot that needs to be filled or confirmed in a multi-turn dialog. |
String |
|
Specifies multiturn dialog context. To continue the dialog, provide this value in the |
Object |
|
Text that Alexa speaks to the user in the multi-turn dialog. |
Object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the utterance results. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Utterance Profiler API defines the following objects.
Locale values
The following table shows valid values for the locale
property.
Locale code | Language |
---|---|
|
Arabic (SA) |
|
German (DE) |
|
English (AU) |
|
English (CA) |
|
English (UK) |
|
English (IN) |
|
English (US) |
|
Spanish (ES) |
|
Spanish (MX) |
|
Spanish (US) |
|
French (CA) |
|
French (FR) |
|
Hindi (IN) |
|
Italian (IT) |
|
Japanese (JP) |
|
Dutch (NL) |
|
Portuguese (BR) |
Related topics
Last updated: Aug 01, 2024