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

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

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

Response body properties

Property Description Type

requestId

The same requestId in the trigger instance request.

String

Failed response body 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.

Was this page helpful?

Last updated: Aug 07, 2024