Skill Invocation API v0

Note: Sign in to the developer console to build or publish your skill.

Warning: You are viewing the SMAPI v0 API documentation. The current version of SMAPI is Version 2. Switch to v2 to view the latest documentation.

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.

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.

Skill Invocation API Request

HTTP method and path

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

Parameters

Field	Description	Parameter Type	Required?
skillId	Unique identifier of skill.	Path	Yes
stage	Stage of the skill. Accepted values are `development` and `live` (case sensitive).	Path	Yes

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
`endpointRegion`	Region of endpoint to be called. Values are "NA" or "EU" or "FE". If "Default" is used, the global default endpoint is used.
`skillRequest.body`	ASK 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
`status`	String that specifies the status of skill invocation. Either `SUCCESSFUL` or `FAILED`.
`invocationRequest.endpoint`	AWS Lambda or HTTPS endpoint for the skill
`invocationRequest.body`	JSON payload that was sent to the skill's AWS Lambda or HTTPS endpoint
`invocationResponse.body`	Payload that was returned by the skill's AWS Lambda or HTTPS endpoint.
`skillExecutionTimeInMilliseconds`	How 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
`code`	Error code that maps to an error message. Developers with different locales should be able to lookup the error description based on this code.
`message`	A 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 /v2/skills/amzn1.ask.skill.a378ab7a-4545-407d-9b68-d0d0c6b75468/stages/development/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?

Provide feedback

Last updated: Dec 02, 2022