Utterance Profiler API

Use the utterance profiler API to test user utterances and improve your skill's interaction model. You can send utterances to the API to see how they resolve to intents and slots in your skill's interaction model. When an utterance doesn't resolve to the right intent or slot, you can update your skill's interaction model and try again, all before writing any code for your skill. The utterance profiler doesn't call an endpoint or invoke a skill, so you don't need to develop the backend service for your skill just to test your skill's interaction model. Because the utterance profiler returns consideredIntents in the response, you can see what intents have been considered and discarded. Thus, 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 do a round-trip test of your skill and view the consideredIntents returned, either through the Alexa Simulator in the developer console or through the Skill Simulation API.

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.

Request
Response
- Response body structure
- Response fields
Examples
- Example request
- Example response

Request

The API's endpoint is https://api.amazonalexa.com. Each API request must have an Authorization header whose value is the access token retrieved from Login with Amazon.

HTTP method and URI path

POST /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/profileNlu

Request body structure

{
  "utterance": "string",
  "multiTurnToken": "string"
}

Request fields

Field	Description	Type
`skillId`	Required. Part of the URI path. The ID of the skill whose interaction model to test.	String
`stage`	Required. Part of the URI path. The stage of the skill model to test. For example, for a skill in the development stage, use `development`. For a published skill, use `live`.	String
`locale`	Required. Part of the URI path. The locale of the skill model to test. For example, `en-US`.	String
`utterance`	Required. Part of the request body. The utterance to use for testing the skill model.	String
`multiTurnToken`	Optional. Part of the request body. Send this field only for multiturn conversations, and only after you receive a multiturn token in the response. Set the value to the token you received in the previous response.	String

Response

Response body structure

{
  "sessionEnded": true,
  "selectedIntent": {
    "name": "string",
    "confirmationStatus": "NONE",
    "slots": {
      "slotName": {
        "name": "string",
        "value": "string",
        "confirmationStatus": "NONE",
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "string",
              "status": {
                "code": "ER_SUCCESS_MATCH"
              },
              "values": [
                {
                  "name": "string",
                  "id": "string"
                }
              ]
            }
          ]
        }
      }
    }
  },
  "consideredIntents": [
    {
      "name": "string",
      "confirmationStatus": "NONE",
      "slots": {
        "slotName": {
          "name": "string",
          "value": "string",
          "confirmationStatus": "NONE",
          "resolutions": {
            "resolutionsPerAuthority": [
              {
                "authority": "string",
                "status": {
                  "code": "ER_SUCCESS_MATCH"
                },
                "values": [
                  {
                    "name": "string",
                    "id": "string"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  ],
  "multiTurn": {
    "dialogAct": {
      "type": "Dialog.ElicitSlot",
      "targetSlot": "string"
    },
    "token": "string",
    "prompt": "string"
  }
}

Response fields

Field	Description	Type
`sessionEnded`	Indicates whether the utterance would cause Alexa to exit the skill. Set to `true` when the utterance would cause Alexa to exit the skill, otherwise set to `false`.	Boolean
`selectedIntent`	The intent that Alexa selected for the utterance in the request.	Intent object
`consideredIntents`	All intents that Alexa considered for the utterance in the request, but did not select.	List 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.	MultiTurn object

MultiTurn object

Field	Description	Type
`dialogAct`	Contains information about the reason for this dialog and the target slot for the user's response in the multiturn dialog.	DialogAct object
`token`	An opaque token that specifies multiturn dialog context. To continue the dialog, provide this value in the `multiTurnToken` field in the next request.	String
`prompt`	The prompt that Alexa speaks to the user in the multiturn dialog.	String

DialogAct object

Field	Description	Type
`type`	The dialog act for the next response from the user in this multiturn dialog. The value is one of `Dialog.ElicitSlot`, `Dialog.ConfirmSlot`, or `Dialog.ConfirmIntent`. For more information, see dialog directives.	String
`targetSlot`	The target slot for the user's response in the multiturn dialog.	String

Examples

Example request

POST /v1/skills/amzn1.ask.skill.abcd1234-.../stages/development/interactionModel/locales/en-US/profileNlu HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Atza|aYcrxwvsxKNYLrzv6nxfQPnhJdPT22en...

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

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1570
Connection: Keep-Alive
Server: Server
Date: Wed, 09 Jan 2019 19:26:34 GMT
X-Amzn-RequestId: abcd1234-...

{
  "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?"
  }
}