Utterance Profiler REST API Reference

Note: Sign in to the developer console to build or publish your skill.

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	`POST /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/profileNlu`

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

Copied to clipboard.

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
`skillId`	Path	Identifies the skill. Valid values: 1 – 255 characters.	String	Yes
`stage`	Path	Indicates stage of the skill. Valid values: `development`, `live`.	String	Yes
`locale`	Path	Locale of the interaction model to test.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "utterance": "i want to travel from seattle",
  "multiTurnToken": null
}

Request body properties

Property	Description	Type	Required
`utterance`	Utterance text to test. Valid value: `active`.	String	Yes
`multiTurnToken`	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
`sessionEnded`	Indicates whether the utterance caused Alexa to exit the skill.	Boolean
`selectedIntent`	Intent that Alexa selected for the utterance.	Intent object
`consideredIntents`	List of intents that Alexa considered, but didn't select.	Array of Intent objects
`multiTurn`	Included when the selected intent has dialog defined and the dialog is not completed. To continue the dialog, provide the value of the `token` in the `multiTurnToken` field in the next request.	Object
`multiTurn.dialogAct`	Prompts to the user.	Object
`multiTurn.dialogAct.type`	Dialog action for the next response from the user in this multi-turn dialog. For more details, see Dialog directives. Valid values: `Dialog.ElicitSlot`, `Dialog.ConfirmSlot`, `Dialog.ConfirmIntent`.	String
`multiTurn.dialogAct.targetSlot`	Target slot that needs to be filled or confirmed in a multi-turn dialog.	String
`multiTurn.token`	Specifies multiturn dialog context. To continue the dialog, provide this value in the `multiTurnToken` field in the next request.	Object
`multiTurn.prompt`	Text that Alexa speaks to the user in the multi-turn dialog.	Object

HTTP status codes

Status	Description
`200 OK`	Response body contains the utterance results.
`400 Bad Request`	Indicates that one or more properties in the request body are invalid. The following example shows the response body with the error and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`401 Unauthorized`	Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. The skill can retry the request by using exponential back-off.
`503 Service Unavailable`	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
`ar-SA`	Arabic (SA)
`de-DE`	German (DE)
`en-AU`	English (AU)
`en-CA`	English (CA)
`en-GB`	English (UK)
`en-IN`	English (IN)
`en-US`	English (US)
`es-ES`	Spanish (ES)
`es-MX`	Spanish (MX)
`es-US`	Spanish (US)
`fr-CA`	French (CA)
`fr-FR`	French (FR)
`hi-IN`	Hindi (IN)
`it-IT`	Italian (IT)
`ja-JP`	Japanese (JP)
`pt-BR`	Portuguese (BR)

Last updated: Jan 27, 2023