Utterance Conflict Detection API

You can use the following operations to find utterances that map to more than one intent in the interaction model for your skill. For information about the types of utterance conflicts and about how to view utterance conflicts in the developer console, see Find Utterance Conflicts in Your Model.

To start getting utterance conflicts, use the get conflicts operation. It can take awhile for the conflict detection job to return the results. At any time, you can get the conflict detection job status. Once the status returns COMPLETED, use get conflicts to see the results.

API endpoint

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

Get conflict detection job status

Request

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions/{version}/conflictDetectionJobStatus

Parameters

Name Located in Description Type Required
skillID URI path Identifier of the skill for which to show utterance conflicts. String Yes
stage URI path Stage of the skill model. Must be development. String Yes
locale URI path Locale of the skill model, for example en-US. String Yes
version URI path Version of the interaction model. String Yes

Response

A successful response shows the job status. If the status is COMPLETED, the response shows the count of utterance conflicts as totalConflicts. If the status is not COMPLETED, the response omits totalConflicts.

{
    "status" : "COMPLETED",
    "totalConflicts": 1
}
Name Description Type
status Status of the job to detect utterance conflicts. String. Values include FAILED, IN_PROGRESS, and COMPLETED.
totalConflicts Count of utterance conflicts, returned only if status is COMPLETED. Long

Get conflicts for skill

Request

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions/{version}/conflicts?nextToken=String&maxResults=Integer

Parameters

Name Located in Description Type Required
skillID URI path Identifier of the skill for which to show utterance conflicts. String Yes
stage URI path Stage of the skill model. Must be development. String Yes
locale URI path Locale of the skill model, for example en-US. String Yes
version URI path Version of the interaction model. String Yes
nextToken Query string Token to continue returning results from the same result set. String No
maxResults Query string Maximum count of results to show at one time. The value must be at least 1 and not greater than 1000. The default value is 100. Integer No

Response

A successful response shows the details of the utterance conflicts.

{
    "metadata" : {
        "resultset": {
            "nextToken": String,
            "totalResults": Integer
        }
    }
    "results": [
        {
            "conflictingUtterance": String,
            "conflicts" : [
                {
                    "sampleUtterance": String,
                    "intent" : {
                        "name": String
                        "slots": {
                            "<slotName>": {
                                "type" : String,
                                "value" : String
                            }
                        }
                    }
                }
            ]
        }
    ],
    "_links":{
        "self" : {
            "href" : String // /v1/skills/{skillId}/conflicts
        },
        "next" : {
            "href" : String // /v1/skills/{skillId}/conflicts?nextToken={nextToken}&maxResults=100
        }
    }
}
Name Description Type
nextToken Token that you can use to continue returning results. String
totalConflicts Total count of utterance conflicts. Integer
conflictingUtterance Utterance, including slot values, that maps to more than one intent. Slot values are in lowercase spoken form, for example the value "4" appears as "four". String
sampleUtterance Sample utterance provided with the interaction model. String

Note that conflicts between utterances that use the AMAZON.SearchQuery or AMAZON.LITERAL slot types are not included.

Response examples

The following response shows an utterance conflict where the value "orange" overlaps between a built-in slot type in one intent and a custom slot type in a different intent.

{
    "metadata": {
        "resultset": {
            "nextToken": "XSDSW123SW73GDW98DHOI",
            "totalResults": 1
        }
    }
    "results": [
        {
            "conflictingUtterance": "I need orange",
            "conflicts":[
                {
                    "sampleUtterance": "I need {colora}",
                    "intent": {
                        "name": "customa",
                        "slots":{
                            "colora": {
                                "type": "AMAZON.Color",
                                "value": orange
                            }
                        }
                    }
                },
                {
                    "sampleUtterance" : "I need {fruit}"
                    "intent": {
                        "name": "customb",
                        "slots": {
                            "fruit": {
                                "type" : "fruit",
                                "value" : orange
                            }
                        }
                    }
                }
            ]
        }
    ]
}

The following response shows an utterance conflict between a custom intent and a built-in intent. Alexa prioritizes the custom intent over the built-in intent, so in the example, "help" always resolves to your intent instead of the built-in. If you want the utterance to map to your custom intent rather than the built-in, leave the conflict in place.

{
    "metadata": {
        "resultset": {
            "nextToken": "hwegwy8t8w7qrsbgfisy97fyhufiw8y",
            "totalResults": 1
        }
    }
    "results": [
        {conflictingUtterance": "Help",
            "conflicts":[
                {
                    "sampleUtterance": "Help",
                    "intent": {
                        "name": "helpCustomIntent"
                    }
                },
                {
                    "intent": {
                        "name:": AMAZON.HelpIntent"
                    }
                }
            ]
        }
    ]
}