Skill Invocation API v1

The Skill Invocation API invokes the AWS Lambda or third-party HTTPS endpoint for a specified skill. A successful response will contain information related to what endpoint was called, and the payload sent to and received from the endpoint. In cases where a request to this API results in an error, the response will contain a description of the problem. In cases where invoking the skill endpoint specifically fails, the response will contain a status attribute indicating that a failure occurred as well as details about what was sent to the endpoint.

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

All SMAPI v1 APIs will throw the following error responses if appropriate: HTTP/1.1 429 TooManyRequestsException if a request is throttled, and HTTP/1.1 503 if a service is unavailable.

You can use this API to invoke those skills for which you are the developer. The skill being invoked must be enabled on your account and must be in the development stage. A call to the skill endpoint will time out after 10 seconds.

The Skill Invocation API must be used only for skill testing purposes.

See also: Alexa Skills Kit Command Line Interface (ASK CLI) Overview and Skill Simulation API

Skill Invocation API Request

HTTP method and path

POST /v1/skills/{skillId}/invocations HTTP/1.1

Request

Request Headers

Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string

Request Body

{
  "endpointRegion": string enum["NA", "EU", "FE", etc],
  "skillRequest": {
    "body": object
  }
}

Request Attributes Definition

Attribute Description
endpointRegionRegion of endpoint to be called. Values are "NA" or "EU" or "FE". If "Default" is used, the global default endpoint is used.
skillRequest.bodyASK request body schema as defined at Request Body Syntax

Skill Invocation API Response

Response Headers

Content-Type: application/json
X-Amzn-RequestId: string

Response Body

200 OK

 {
   "status": string enum["SUCCESSFUL", "FAILED"],
   "result": {
     "skillExecutionInfo": {
       "invocationRequest": {
         "endpoint": string,
         "body": object
       },
       "invocationResponse": {
         "body": object     
       },
       "metrics": {
         "skillExecutionTimeInMilliseconds": integer
       }
     },
     "error": {
       "message": string
     }
   }
 }
Attribute Description
statusString that specifies the status of skill invocation. Either SUCCESSFUL or FAILED.
invocationRequest.endpointAWS Lambda or HTTPS endpoint for the skill
invocationRequest.bodyJSON payload that was sent to the skill's AWS Lambda or HTTPS endpoint
invocationResponse.bodyPayload that was returned by the skill's AWS Lambda or HTTPS endpoint.
skillExecutionTimeInMillisecondsHow long, in milliseconds, it took the skill's AWS Lambda or HTTPS endpoint to process the request.

Errors

Error Response Body

{
  "message": string
}
Attribute Description
codeError code that maps to an error message. Developers with different locales should be able to lookup the error description based on this code.
messageA human-readable description of the error

Error Codes in Response

Response Description
400 Bad Request Invalid or missing data.
403 Forbidden API user does not have permission to call this API or is currently in a state that does not allow invocation of this skill.
404 Not Found The specified skill was not found.

Sample Skill Invocation Request

HTTP Method and Path

POST /v1/skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/invocations

Request Headers

Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json

Request Body

{
  "endpointRegion": "NA",
  "skillRequest": {
    "body": {
      "version": "1.0",
      "session": {
        "new": true,
        "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
        "application": {
          "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
        },
        "attributes": {},
        "user": {
          "userId": "amzn1.ask.account.12345ABCDEFGH"
        }
      },
      "context": {
        "System": {
          "application": {
            "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
          },
          "user": {
            "userId": "amzn1.ask.account.12345ABCDEFGH"
          }
        }
      },
      "request": {
        "type": "IntentRequest",
        "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
        "timestamp": "2017-08-14T04:20:20Z",
        "locale": "en-US",
        "intent": {
          "name": "SayHello"
        }
      }
    }
  }
}

Sample Skill Invocation Response (200 OK) - Successful

This response represents a successful response to an intent request.

Response Headers

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: <value>

Response Body

{
  "status": "SUCCESSFUL",
  "result": {
    "skillExecutionInfo": {
      "invocationRequest": {
        "endpoint": "arn:aws:lambda:us-east-1:123456789:function:HelloWorld",
        "body": {
          "version": "1.0",
          "session": {
            "new": true,
            "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
            "application": {
              "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
            },
            "attributes": {},
            "user": {
              "userId": "amzn1.ask.account.12345ABCDEFGH"
            }
          },
          "context": {
            "System": {
              "application": {
                "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
              },
              "user": {
                "userId": "amzn1.ask.account.12345ABCDEFGH"
              }
            }
          },
          "request": {
            "type": "IntentRequest",
            "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
            "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
  }
}

Sample Skill Invocation Response (200 OK) - Failed

This response represents a case where the HTTP code is 200 OK, but the contents of the response represent a failure, due to the skill's endpoint timing out, and exceeding the 10 seconds limit.

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: <value>

{
  "status": "FAILED",
  "result": {
    "skillExecutionInfo": {
      "invocationRequest": {
        "endpoint": "arn:aws:lambda:us-east-1:123456789:function:HelloWorld",
        "body": {
          "version": "1.0",
          "session": {
            "new": true,
            "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
            "application": {
              "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
            },
            "attributes": {},
            "user": {
              "userId": "amzn1.ask.account.12345ABCDEFGH"
            }
          },
          "context": {
            "System": {
              "application": {
                "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
              },
              "user": {
                "userId": "amzn1.ask.account.12345ABCDEFGH"
              }
            }
          },
          "request": {
            "type": "IntentRequest",
            "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
            "timestamp": "2017-08-14T04:20:20Z",
            "locale": "en-US",
            "intent": {
              "name": "SayHello"
            }
          }
        }
      },
      "invocationResponse": null,
      "metrics": null
    },
    "error":  {
      "message": "Request to skill endpoint timed out."
    }
  }
}

Sample Skill Invocation Response (400 Bad Request)

This response occurs when no endpoint was found for the specified region.

Response Headers

HTTP 400 Bad Request
Content-Type: application/json
X-Amzn-RequestId: <value>

Response Body

{
  "message": "No endpoint was found for the specified region."
}
Was this page helpful?

Last updated: Dec 02, 2022