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).

HTTP header

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

Parameters of HTTP header

Parameter	Description	Example
Content-Type	Content type of the resource. Set to application/x-www-form-urlencoded.	Content-Type: application/x-www-form-urlencoded

Request body properties

Parameter	Description	Example
grant_type	Set to client_credentials.	grant_type=client_credentials
client_id	Alexa Client Id value from the developer console.	client_id={myclientID}
client_secret	Alexa Client Secret value from the developer console.	client_secret={myclientSecret}
scope	Set to alexa::routines:triggerinstances:write.	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	POST /v1/routines/triggerInstances

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
access token	Header	LWA token. For more details, see Get an Access Token for SMAPI.	String	Yes

Request body example

Trigger instance unicast request body example  

Trigger instance multicast request body example  

Request body properties

Property	Description	Type	Required
requestId	Unique identifier for a specific request. It can be from one character to up to 100 characters.	String	Yes
delivery	Identifies if the trigger instance is for one Alexa account recipient (unicast) or multiple Alexa account recipients (multicast). Acceptable values are: UNICAST, MULTICAST.	String	Yes
trigger	Information for the trigger instance.	Object	Yes
trigger.name	The trigger name that is defined in the trigger registration payload. It can be from one character to up to 50 characters.	String	Yes
trigger.parameters	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
recipients	Recipient information that you have configured the trigger for.	Array of objects	Yes for UNICAST only
recipients.type	Type of the event recipient value. In this release, the acceptable value is USER, which means the recipient is a user, not an unit, or other entities.	String	Yes for UNICAST only
recipients.value	An object that describes the event recipient. For the USER type, this value is an object to represent the ID of the recipient.	Object	Yes for UNICAST only
recipients.value.id	The unique identifier of the recipient. Th format is amzn1.ask.account.<unique-ID>. This id is the same as the userId that is explained in the custom skill request session object.	String	Yes for UNICAST only
recipients.scope	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
recipients.scope.type	Type of the provided token. In this release, the supported value is BearerToken.	String	No
recipients.scope.token	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

Successful response example  

Response body properties

Property	Description	Type
requestId	The same requestId in the trigger instance request.	String

Failed response body example

Error response example  

Response body properties

Property	Description	Type
requestId	The same requestId that was sent in the trigger instance request.	String
type	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
message	The error message contains a generic description of the error condition in English.	String

HTTP status codes

HTTP status code	Type	Description
202	OK	Operation succeeded.
400	InvalidRequest	The request payload has invalid parameters.
401	InvalidAccessToken	The access token is invalid.
403	InsufficientPermission	The requester doesn't have access to the trigger type.
404	ResourceNotFound	The request resource isn't found.
429	Throttled	The server received too many requests.
500	InternalError	An internal error occurred when processing the request.
503	ServiceUnavailable	The server is unavailable to accept the request.

Related topics

• Get Started with Creating Custom Triggers for Routines

---

---

Last updated: Nov 27, 2023