Skill Invocation REST API Reference v2


Use the Skill Invocation REST API to test your custom skill. You can invoke skill at the Amazon Web Services (AWS) Lambda or HTTPS endpoint where the skill code resides and receive the response payload.

To use the Skill Invocation API, your skill must meet the following requirements:

  • The skill must be a custom skill.
  • The skill must belong to the developer account that you use to call this API.
  • The skill must be enabled.
  • The skill must be in the development or live stage.

API endpoint

The endpoint of the Skill Invocation 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 Skill Invocation API includes the following operations.

Operation HTTP method and URI

Invoke skill

POST /v2/skills/{skillId}/stages/{stage}/invocations

Invoke skill

Invoke the specified skill for testing.

Request

To invoke a skill, you make a POST request to the invocations resource.

Request path and header example

Copied to clipboard.

POST /v2/skills/{skillId}/stages/{stage}/invocations
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

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "endpointRegion": "NA",
    "skillRequest": {
        "body": {
            "version": "1.0",
            "session": {
                "new": true,
                "sessionId": "amzn1.echo-api.session.1",
                "application": {
                    "applicationId": "amzn1.ask.skill.1"
                },
                "attributes": {},
                "user": {
                    "userId": "amzn1.ask.account.1"
                }
            },
            "context": {
                "System": {
                    "application": {
                        "applicationId": "amzn1.ask.skill.1"
                    },
                    "user": {
                        "userId": "amzn1.ask.account.1"
                    }
                }
            },
            "request": {
                "type": "IntentRequest",
                "requestId": "amzn1.echo-api.request.1",
                "timestamp": "2017-08-14T04:20:20Z",
                "locale": "en-US",
                "intent": {
                    "name": "SayHello"
                }
            }
        }
    }
}

Request body properties

Property Description Type Required

endpointRegion

AWS endpoint region or HTTPS endpoint where the skill resides.
Valid values: NA, EU, FE, default.

String

Yes

skillRequest

Current state of the list.
Valid value: active.

Object

Yes

skillRequest.body

Request body schema.
For details, see Request body syntax.

Object

Yes

Response

A successful response returns HTTP 200 OK, along with the skill response. 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 following example shows a response.

{
    "status": "SUCCESSFUL",
    "result": {
        "skillExecutionInfo": {
            "invocationRequest": {
                "endpoint": "arn:aws:lambda:us-east-1:1:function:HelloWorld",
                "body": {
                    "version": "1.0",
                    "session": {
                        "new": true,
                        "sessionId": "amzn1.echo-api.session.1",
                        "application": {
                            "applicationId": "amzn1.ask.skill.1"
                        },
                        "attributes": {},
                        "user": {
                            "userId": "amzn1.ask.account.1"
                        }
                    },
                    "context": {
                        "System": {
                            "application": {
                                "applicationId": "amzn1.ask.skill.1"
                            },
                            "user": {
                                "userId": "amzn1.ask.account.1"
                            }
                        }
                    },
                    "request": {
                        "type": "IntentRequest",
                        "requestId": "amzn1.echo-api.request.1",
                        "timestamp": "2017-08-14T04:20:20Z",
                        "locale": "en-US",
                        "intent": {
                            "name": "SayHello"
                        }
                    }
                }
            },
            "invocationResponse": {
                "body": {
                    "version": "1.0",
                    "sessionAttributes": {},
                    "response": {
                        "outputSpeech": {
                            "type": "PlainText",
                            "text": "hello, world"
                        },
                        "shouldEndSession": true
                    }
                }
            },
            "metrics": {
                "skillExecutionTimeInMilliseconds": 100
            }
        },
        "error": null
    }
}

Response body properties

Property Description Type

status

Indicates the success or failure of the skill invocation.
Valid values: SUCCESSFUL, FAILED.

String

result

Describes the result of the invocation.

Object

result.skillExecutionInfo

Includes the payload sent in the request and the payload received from the endpoint.

Object

result.skillExecutionInfo.invocationRequest

Request parameters.

Object

result.skillExecutionInfo.invocationRequest.endpoint

AWS endpoint region or HTTPS endpoint of the skill.

String

result.skillExecutionInfo.invocationRequest.body

JSON payload sent in the request to your skill.
For details, see Request body syntax.

Object

result.skillExecutionInfo.invocationResponse

(Optional) JSON payload returned by the skill.
For details, see Response body syntax.

Object

result.skillExecutionInfo.metrics

Metrics recorded for the request and response.

Object

result.skillExecutionInfo.metrics.skillExecutionTimeInMilliseconds

How long, in milliseconds, it took the AWS Lambda or HTTPS endpoint to process the request.

Integer

result.error

Reports any errors that occurred.

Object

result.error.message

(Optional) Describes the problem.

String

HTTP status codes

Status Description

200 OK

Response body contains the invocation results from your skill.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
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 included token expired or isn't valid. Or, you don'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.


Was this page helpful?

Last updated: Jan 26, 2024