Utterance Conflict Detection API Reference

Use the Utterance Conflict Detection REST API to find utterances that map to more than one intent in your skill's interaction model. For more details about utterance conflicts, see Find Utterance Conflicts in Your Model.

API endpoint

The endpoint of the Utterance Conflict Detection 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 Conflict Detection API includes the following operations.

Operation HTTP method and URI

Detect utterance conflicts

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

Get conflict detection status

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

Detect utterance conflicts

Detect utterance conflicts in the specified interaction model. It might take awhile to get the results of the conflict detection. Use Get conflict detection status to get the status of the request.

Request

To detect conflicts, you make a GET request to the conflicts resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions/{version}/conflicts&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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

version

Path

Version of the interaction model to test.

String

Yes

locale

Path

Locale of the interaction model to test.

String

Yes

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1 – 1000. Default: 100.

Integer

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the details of the utterance conflicts. 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 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 another intent.

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. 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 intent, leave the conflict in place.

Response body properties

Property Description Type

metadata

Information about the set of results.

Object

metadata.resultset

Indicates there is more content. If present, the response contains a subset of the annotations. When there is no more content, resultset isn't included in the response.

Object

metadata.resultset.nextToken

Identifies the next set of results to return. The token expires in 24 hours.
Use this value for the nextToken parameter in a subsequent Detect utterance conflicts request.

String

metadata.resultset.totalCount

Identifies the total number of results found. This value might be more than maxResults.

Integer

results

Description

Array of objects

results.conflictingUtterance

Utterance that causes conflicts among different intents.

String

results.conflicts

Identifies the intents and slots with which the utterance conflicts.

Array of objects

results.conflicts[].sampleUtterance

Sample utterance defined for this intent in the interaction model.

String

results.conflicts[].intent

Intent defined for the sample utterance in the interaction model.

Object

results.conflicts[].intent.name

Name of the intent with which the utterance conflicts.

String

results.conflicts[].intent.slots

(Optional) Slot that match the conflicting utterance.

Object

results.conflicts[].intent.slots.<slotname>.type

Slot type.

String

results.conflicts[].intent.slots.<slotname>.value

(Optional) Resolved slot value.
Values are given in the lowercase spoken form, for example the value "4" appears as "four."

String

_links

Links for result navigation.
Defined in JSON Hypertext Application Language specification.

_links object

HTTP status codes

Status Description

200 OK

Response body contains the details of the utterance conflicts.

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.

Get conflict detection status

Get the current status of a recently submitted conflict detection request. After the request completes, use Detect utterance conflicts to get the results.

Request

To get the status of a conflict detection request, you make a GET request to the conflictDetectionJobStatus resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}/versions/{version}/conflictDetectionJobStatus
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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

version

Path

Version of the interaction model to test.

String

Yes

locale

Path

Locale of the interaction model to test.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with status of the conflict detection. 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

{
    "status": "COMPLETED",
    "totalConflicts": 1
}

Response body properties

Property Description Type

status

Status of the utterance conflict detection request.
Valid values: IN_PROGRESS, COMPLETED, FAILED.

String

totalConflicts

Total number of conflicts detected.

Long

HTTP status codes

Status Description

200 OK

Response body contains the status of the conflict detection request.

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 Conflict Detection 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