Interaction Model Management REST API Reference v1

Use the Interaction Model Management REST API to manage the custom voice interaction model for your skill. For details about the custom voice interaction model, About Voice Interaction Models. For requirements, see Interaction model limits.

To create the interaction model in the developer console, see Create the Interaction Model for Your Skill. For details about the schema, see Interaction Model Schemas.

API endpoint

The endpoint of the Interaction Model Management 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 Interaction Model Management API includes the following operations.

Operation HTTP method and URI

Check interaction model existence

HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

Get interaction model

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

Update interaction model

PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}

Check interaction model existence

Check whether the interaction model exists for the specified skill, stage, and locale.

Request

To check the existence of the interaction model, you make a HEAD request to the interactionModel resource.

Request path and header example

Copied to clipboard.

HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
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

locale

Path

Locale of the skill.

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 204 No Content to indicate that the interaction model exists. 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

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Interaction model exists for the specified skill, stage, and locale.
The response header contains an ETag parameter that identifies the version of the resource.

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 interaction model

Get the interaction model for the specified skill.

Request

To get the interaction model, you make a GET request to the interactionModel resource.

Request path and header example

Copied to clipboard.

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

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

locale

Path

Locale of the skill.

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 the interaction model. 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

{
    "version": "2",
    "description": "Created version 2 of interaction model.",
    "interactionModel": {
        "languageModel": {
            "invocationName": "my space facts",
            "modelConfiguration": {
                "fallbackIntentSensitivity": {
                    "level": "LOW"
                }
            },
            "intents": [{
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.FallbackIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StartOverIntent",
                    "samples": []
                },
                {
                    "name": "GetNewFactIntent",
                    "slots": [],
                    "samples": [
                        "Give me a fact",
                        "tell me a fact"
                    ]
                }
            ],
            "types": [{
                "name": "Planet_facts",
                "values": [{
                        "name": {
                            "value": "Mercury"
                        }
                    },
                    {
                        "name": {
                            "value": "Venus"
                        }
                    },
                    {
                        "name": {
                            "value": "Earth"
                        }
                    },
                    {
                        "name": {
                            "value": "Mars"
                        }
                    }
                ]
            }]
        },
        "dialog": {
            "intents": [{
                "name": "GetNewFactIntent",
                "confirmationRequired": false,
                "prompts": {},
                "slots": [{
                    "name": "Answer",
                    "type": "Planet",
                    "confirmationRequired": false,
                    "elicitationRequired": true,
                    "prompts": {
                        "elicitation": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer"
                    }
                }]
            }],
            "delegationStrategy": "ALWAYS"
        },
        "prompts": [{
            "id": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer",
            "variations": [{
                "type": "PlainText",
                "value": "What planet?"
            }]
        }]

    }
}

Response body properties

Property Description Type

version

Identifies the version of the interaction model.

String

description

Describes this version of the interaction model.

String

interactionModel

Defines the properties of the interaction model, such as invocation name, intents, and slots.

Interaction Model object

HTTP status codes

Status Description

200 OK

Response body contains the interaction model for the specified skill, stage, and locale.
The response header contains an ETag parameter that identifies the version of the resource.

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.

Update interaction model

Create or update the interaction model for the specified skill. On success, a build starts on the interaction model. To get the build status, use Get skill status.

Request

To create an interaction model, you make a PUT request to the interactionModel resource.

Request path and header example

Copied to clipboard.

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

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

locale

Path

Locale of the skill.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "description": "Created version 1 of interaction model.",
    "interactionModel": {
        "languageModel": {
            "invocationName": "my space facts",
            "modelConfiguration": {
                "fallbackIntentSensitivity": {
                    "level": "LOW"
                }
            },
            "intents": [{
                    "name": "AMAZON.CancelIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.HelpIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StopIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.FallbackIntent",
                    "samples": []
                },
                {
                    "name": "AMAZON.StartOverIntent",
                    "samples": []
                },
                {
                    "name": "GetNewFactIntent",
                    "slots": [],
                    "samples": [
                        "Give me a fact",
                        "tell me a fact"
                    ]
                }
            ],
            "types": [{
                "name": "Planet_facts",
                "values": [{
                        "name": {
                            "value": "Mercury"
                        }
                    },
                    {
                        "name": {
                            "value": "Venus"
                        }
                    },
                    {
                        "name": {
                            "value": "Earth"
                        }
                    },
                    {
                        "name": {
                            "value": "Mars"
                        }
                    }
                ]
            }]
        },
        "dialog": {
            "intents": [{
                "name": "GetNewFactIntent",
                "confirmationRequired": false,
                "prompts": {},
                "slots": [{
                    "name": "Answer",
                    "type": "Planet",
                    "confirmationRequired": false,
                    "elicitationRequired": true,
                    "prompts": {
                        "elicitation": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer"
                    }
                }]
            }],
            "delegationStrategy": "ALWAYS"
        },
        "prompts": [{
            "id": "Elicit.Intent-GetNewFactIntent.IntentSlot-Answer",
            "variations": [{
                "type": "PlainText",
                "value": "What's your answer?"
            }]
        }]

    }
}

Request body properties

Property Description Type Required

description

Describes this version of the interaction model.

String

Yes

version

Defines the interaction model, such as invocation name, intents, and slots.

Interaction Model object

Yes

Response

A successful response returns HTTP 202 Accepted, that indicates that the interaction model version was created. The response header contains a Location parameter with a URL to the build status. 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

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

202 Accepted

Successful creation of the interaction model version and a build is in progress. The response header contains a Location parameter that includes a URL to the build status.

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 Interaction Model Management 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: May 10, 2023