Routines Trigger Service Provider Interface

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

Note: The use of custom triggers for routines is offered as a developer preview and might change as Amazon receives feedback and iterates on the feature. If you have published an Alexa skill and would like to participate in developer preview, contact Amazon and get a sneak peek into the workings of the custom triggers for routines.

A UNICAST delivery has a unique recipient for the trigger parameters. If you use UNICAST as the delivery type in your trigger definition, you must implement the Routines Trigger Service Provider Interface (SPI) in your Alexa skill to handle requests from your customer to create or delete a routine. When a customer sets up a routine with your trigger, Alexa sends a callback request to your skill and your skill must send a response to this callback request.

Requests and responses

The following table shows the available operations with the Routines Trigger SPI.

Operation	Description
`Routines.Trigger.Create`	When a customer sets up a routine with your trigger, Alexa sends a `Routines.Trigger.Create` event to your skill.
`Routines.Trigger.Delete`	When a customer deletes a routine that contains your trigger, Alexa sends a `Routines.Trigger.Delete` event to your skill.

Trigger request

When a customer creates a routine with your trigger or enables a routine that contains your trigger from the Routines Gallery, Alexa sends an event to your Alexa skill with the following JSON payload.

When a customer deletes a routine with your trigger or disables a routine that contains your trigger from the Routines Gallery, Alexa sends an event to your skill with the following JSON payload.

Request parameters

The following table shows the request parameters.

Property	Description	Type	Required
`request`	Details of the trigger request from the user.	Object	Yes
`timestamp`	The date and time when Alexa sends the request as an ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`.	String	Yes
`requestId`	A unique identifier for the specific request.	String	Yes
`type`	The routines request type. The acceptable values are: `Routines.Trigger.Create` or `Routines.Trigger.Delete`.	String	Yes
`trigger`	Information of the trigger that is created or deleted by the customer.	Object	Yes
`trigger.name`	Trigger name that is defined in trigger definition.	String	Yes
`trigger.parameters`	Inputs received during trigger configuration. The values in this object correspond to the trigger parameters that are defined in the trigger registration. Alexa collects your customer's trigger configuration from the trigger detail page and passes them to your skill as the parameters. For details about trigger registration, see Step 2.3 Deploy the skill to development and submit your trigger definition for registration in "Steps for Create Custom Triggers for Routines".	Object	Yes
`recipient`	Recipient information that you have configured the trigger for.	Object	Yes
`recipient.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 any other entities.	String	Yes
`recipient.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
`recipient.value.id`	A string that represents a unique identifier for the Amazon account for which the skill is enabled. The format is `amzn1.ask.account.<unique-ID>`.	String	Yes
`recipient.scope`	Use this parameter when the user is a customer who has an account that is linked with the Alexa skill. This parameter holds the customer's account linking information, such as access token. For details about account linking, see Add account linking.	Object	Yes
`recipients.scope.type`	Type of the provided token. In this release, the supported value is `BearerToken`.	String	Yes
`recipients.scope.token`	Value of the token to access the account information of the customer.	String	Yes

Trigger response

A successful response returns an HTTP status 200 Okay. On error, the response returns the appropriate error HTTP status code. For more details, see HTTP status codes.

{ 
  "requestId": "<requestID>"
}

Response parameters

The following table shows the response parameters.

Property	Description	Type	Required
`requestId`	The `requestId` is the unique request identifier that Alexa sends in the `Routines.Trigger.Create` or `Routines.Trigger.Delete` request.	String	Yes

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.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023