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
orlive
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
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
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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
Header |
String |
Yes |
Request body example
{
"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 |
---|---|---|---|
|
AWS endpoint region or HTTPS endpoint where the skill resides. |
String |
Yes |
|
Current state of the list. |
Object |
Yes |
|
Request body schema. |
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 |
---|---|---|
|
Indicates the success or failure of the skill invocation. |
String |
|
Describes the result of the invocation. |
Object |
|
Includes the payload sent in the request and the payload received from the endpoint. |
Object |
|
Request parameters. |
Object |
|
AWS endpoint region or HTTPS endpoint of the skill. |
String |
|
JSON payload sent in the request to your skill. |
Object |
|
(Optional) JSON payload returned by the skill. |
Object |
|
Metrics recorded for the request and response. |
Object |
|
How long, in milliseconds, it took the AWS Lambda or HTTPS endpoint to process the request. |
Integer |
|
Reports any errors that occurred. |
Object |
|
(Optional) Describes the problem. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the invocation results from your skill. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
Last updated: Aug 01, 2024