Routines Trigger Instance REST API Reference
The Routines Trigger Instance API dispatches custom triggers for Alexa routines.
API endpoint
Development endpoint
During skill development, you can test sending trigger instances by using the following endpoint:
- North America:
https://api.amazonalexa.com/v1/routines/triggerInstances/stages/development
Production endpoint
After Amazon certifies your skill, you can use the following production endpoint:
- North America:
https://api.amazonalexa.com/v1/routines/triggerInstances
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). Set the scope to scope=alexa::routines:triggerinstances:write
.
Operations
The Custom Trigger for Routines API includes the following operation.
Operation | HTTP method and URI |
---|---|
|
Dispatch a trigger instance
Submits a trigger instance by specifying the trigger information and target recipient.
Request
To dispatch a trigger instance, make a POST
request to the routines/triggerInstances
resource.
Request path and header example
POST /v1/routines/triggerInstances
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
LWA token. For more details, see Get an Access Token for SMAPI. |
String |
Yes |
Request body example
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Unique identifier for a specific request. It can be from one character to up to 100 characters. |
String |
Yes |
|
Identifies if the trigger instance is for one Alexa account recipient (unicast) or multiple Alexa account recipients (multicast). Acceptable values are: |
String |
Yes |
|
Information for the trigger instance. |
Object |
Yes |
|
The trigger name that is defined in the trigger registration payload. It can be from one character to up to 50 characters. |
String |
Yes |
|
The parameters that match with the trigger parameters object sent in the Service Provider Interface (SPI) request to configure the trigger. For more details, see Routines Trigger Service Provider Interface. |
Object |
Yes |
|
Recipient information that you have configured the trigger for. |
Array of objects |
Yes for |
|
Type of the event recipient value. In this release, the acceptable value is |
String |
Yes for |
|
An object that describes the event recipient. For the |
Object |
Yes for |
|
The unique identifier of the recipient. Th format is |
String |
Yes for |
|
Use this parameter when the user has an account that is linked with the Alexa skill. This parameter holds the user's account linking information, such as access token. |
Object |
No |
|
Type of the provided token. In this release, the supported value is |
String |
No |
|
Value of the token to access the user's account information. |
String |
No |
Response
A successful response returns HTTP 202 OK
with a response body that shows the requestId
. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Successful response body example
Response body properties
Property | Description | Type |
---|---|---|
|
The same |
String |
Failed response body example
Response body properties
Property | Description | Type |
---|---|---|
|
The same |
String |
|
The error type is a string that uniquely identifies an error condition that is observed in the Alexa service. For more details, see Error HTTP status codes. |
String |
|
The error message contains a generic description of the error condition in English. |
String |
HTTP status codes
HTTP status code | Type | Description |
---|---|---|
|
|
Operation succeeded. |
|
|
The request payload has invalid parameters. |
|
|
The access token is invalid. |
|
|
The requester doesn't have access to the trigger type. |
|
|
The request resource isn't found. |
|
|
The server received too many requests. |
|
|
An internal error occurred when processing the request. |
|
|
The server is unavailable to accept the request. |
Related topics
Last updated: Aug 07, 2024