Routines Trigger Service Provider Interface


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 to Your Alexa Skill.

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.

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?

Last updated: Sep 10, 2024