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, as discussed in Intent Debugging, or through the Skill Simulation API.

You can also use the utterance profiler in the Alexa Skills Kit developer console. For more information, see Test Your Utterances and Improve Your Interaction Model.

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?"
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment