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
  • HTTP method and URI path
  • Request body structure
  • Request fields
• 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

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

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