Steps to Create Custom Triggers for Routines

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.

Complete the following steps to create custom triggers for routines. You can implement custom triggers for routines by updating an existing skill or creating a new skill.

Prerequisites

Before you start, you must meet the following requirements:

Publish an Alexa skill.
Get permission to use the custom triggers for routines feature. To get permission to participate in the developer preview, contact Amazon.
Create an Amazon developer account.
Install the latest version of the Alexa Skills Kit Command Line Interface (ASK CLI). For more details, see ASK CLI.
Install a representational state transfer (REST) client or the curl command-line tool.

Important: Child-directed skills and HIPAA skills aren't eligible to use routines, and therefore can't integrate custom triggers with Alexa routines.

Steps to create custom triggers for routines

Custom trigger for routines API Workflow

To create custom triggers for routines, complete the following steps:

Create a skill and update the skill manifest.
Publish the skill, define your trigger, and deploy to development.
Update your skill to listen to routine callback (UNICAST only).
Test your trigger.
Change the development endpoint to production.
Customer sets up routines by using your trigger.
Send a trigger instance through the REST API.

Step 1: Create a skill and update the skill manifest

First you create a new skill, and then you modify the skill.json manifest by adding a routines section. The routines skill type registers new triggers and also enables Alexa and your skill to securely communicate with each other.

Note: If you have an existing skill, skip step 1.1 and directly go to step 1.2 to update the skill.json manifest.

1.1 Create a skill

You can create a new skill on the developer console or by using the ASK CLI.

To create a skill in the developer console

Follow the instructions in Create a New Skill.

Note: Don't create a Flash Briefing skill for custom triggers for routines because the Flash Briefing skill doesn't support permissions. You must set permissions for implementing custom triggers for routines.

To create a skill by using the ASK CLI

At the command prompt, run the ask new command.

For details, see the ASK CLI new command.

1.2 Update the skill manifest `skill.json`

In this step, you update the skill manifest file.

To update the skill.json

1. If you created a skill on the developer console, you can clone your Alexa skill into your local workspace. To clone your Alexa skill from the developer console into your local workspace, at the command prompt, run the command ask init --hosted-skill-id <hosted-skill-id>.

For more details, see init command.

Tip: If you encounter errors after you runn the command ask init --hosted-skill-id <hosted-skill-id>, you probably haven't configured your ASK CLI. Try running ask configure first.

2. Update the apis section of your skill manifest with routines. For details about the parameter descriptions in the routines skill manifest, see Routines Skill Manifest.

3. In the skill manifest, verify that permissions array is present. The permissions array is used to specify an array of named permissions that the skill can use.

For details, see permissions.

4. If your skill.json doesn't have permissions, you must add permissions so that you can get {clientID} and {clientSecret} to call the routines custom trigger API out of session in Step 4 and Step 7.

The following example shows a skill manifest with the apis section updated to include routines and with the permissions section included.

Important: The permissionssection must have at least one permission listed. If you don't include any permissions in your skill.json, your skill can't display the {clientID} and {clientSecret} in the developer console.

5. To update the skill manifest, run the command ask smapi update-skill-manifest -g development -s <hosted-skill-id> -manifest "file:skill.json".

6. (Optional) If needed, add account linking support.

For details about account linking, see Add Account Linking to Your Alexa Skill.

Step 2: Publish your skill, define your trigger, and deploy to development

In step 2, you publish the skill, define your trigger file, deploy the package to development, and then submit your trigger definition for registration.

2.1 Certify and publish the skill

You must get your skill published to live for the triggers to be displayed in the Alexa app. This means that you must first submit the skill for certification. Afterwards, you can create and submit the trigger definition file for registration in development stage in Step 2.3.

To certify and publish your skill

Follow the requirements and guidelines in Certify and Publish Your Skill.

2.2 Create a trigger definition file

In this step, you create a trigger definition file in JSON format. The trigger definition file name should match with the locale where you intend your trigger to be available; for example en-US.json.

Note: In this release, custom triggers for routines supports the following locales: en-US, en-CA.

The trigger definition must contain the trigger name, display title, delivery type, display categories, and keywords. For details about trigger definition requirements, see Trigger Definition.

To create a trigger definition file

1. Create trigger definition file in JSON format, such as en-US.json.

2. Save your trigger definition file in the /skill-package/routines/triggers/<ExampleTriggerName> directory.

The following example shows a skill package directory where MyShoppingTrigger is the example trigger name.

> skill-package/
  > routines/ 
    > triggers/ 
      > MyShoppingTrigger/ 
        > en-US.json 
  > skills.json

3. Add content to your trigger definition JSON file.

The following JSON code shows a trigger definition example with the UNICAST delivery type.

2.3 Deploy your skill to development and submit your trigger definition for registration

First, you deploy your skill to register the updated manifest. Then, you register your trigger definition with Amazon and enable your skill in development.

To deploy your skill, submit your updated trigger definition, and enable your skill

1. Follow the instructions in Deploy your skill.

Tip: To verify that your skill manifest is in the correct state, you can get the skill manifest by running the ask smapi get-skill-manifest -s <SKILL_ID> -g development --profile <PROFILE> command. For details, see get-skill-manifest.

2. To register your trigger definition with Alexa, contact Amazon and submit your trigger definition JSON file to Amazon.

3. After you submit your trigger definition for registration, you must enable your skill in the development stage by using the SMAPI Enable skill REST API operation. Set the {stage} to development in the PUT request path. This step prevents your customers from accessing this version of your trigger when you are still testing and debugging it.

Step 3: Update your skill to listen to routine callback (UNICAST only)

Important: Do not send UNICAST trigger instances to customers who have disabled your skill.

This step is for UNICAST triggers only.

UNICAST trigger is a trigger notification that is unique to a specific customer. In comparison, a MULTICAST trigger is generic and shared among multiple recipients.

If you use a UNICAST delivery type in your trigger type definition, as shown in the example in Step 2, you must know which customer is interested in your trigger occurrence. This means that you must update your Alexa skill to handle requests when your customer creates a routine with your trigger. You must implement the Routines Trigger Service Provider Interface (SPI) in your skill so that it can handle routine creation callback and deletion callback.

To update your skill to respond to a routine callback

1. In your skill manifest skill.json, include the regions and endpoint objects in the apis section.

For details, see apis object for routines.

2. In the request HTTP header, use the same Alexa skill request format as explained in Request and Response JSON Reference.

3. Validate that the request comes from Alexa as instructed in Manually verify that the request was sent by Alexa.

4. (Optional) If you deploy your skill to Amazon Web Services (AWS) Lambda, have your AWS Lambda grant ASK permission as instructed in Configure the trigger for a Lambda function.

5. To process the trigger creation event, you must update your skill to handle request type Routines.Trigger.Create.

The following example JavaScript code shows how to handle the request type Routines.Trigger.Create.

The following example Java skill code uses AWS Lambda for handling Routines.Trigger.Create and Routines.Trigger.Delete requests.

For more details about the Routines Trigger SPI, see Routines Trigger Service Provider Interface.

Step 4: Test your trigger on your development account

In this step, you create a routine on your development account to receive a trigger instance from your skill.

4.1 Enable your skill and create a routine

Before you create a routine, you must first enable your skill in development stage.

To enable your skill and create a routine

On the Home page of your Alexa app, tap More > Skills & Games > Your Skills > Dev, locate the name of your skill and then tap Enable.
With the custom trigger you defined in Step 2, create a routine.

The associated trigger shows up with the DEV tag in the routine. After you create a routine, your skill should receive an SPI call from Alexa for Unicast triggers.

4.2 Get an access token with the curl command

You can get an access token through a curl command.

To get an access token with a curl command

1. Copy the following curl command.

Copied to clipboard.

    curl -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&client_id={clientID}&client_secret={clientSecret}&scope=alexa::routines:triggerinstances:write' \
    https://api.amazon.com/auth/o2/token

2. In the developer console, on the Permissions tab, locate your clientID and clientSecret for your skill.

3. Copy your {clientID} and {clientSecret}.

4. In the curl command syntax from step 1, paste your clientID and clientSecret into the placeholders {clientID} and {clientSecret} from step 3.

5. For authentication with the Routines Trigger API, make sure the scope is set to scope=alexa::routines:triggerinstances:write.

Note: Use client_credentials as the grant_type. The authorization-code grant is not supported with the scope alexa::routines:triggerinstances:write.

6. At the command prompt, run the curl command that you created in the previous steps.

7. Verify that you receive an access_token that looks similar to the following success response example. In this example, the access token that starts with Atc| is the Bearer token that you can use in Step 4.3 and in Step 7. Typically, the token has an expiration time. In this example, the token expires in one hour (3600 seconds).

{
        "access_token":"Atc|{someToken}",
        "expires_in":3600,
        "scope":"alexa::routines:triggerinstances:write",
        "token_type":"Bearer"
}

4.3 Post a test trigger instance

To dispatch a test trigger instance to yourself, you make a POST request.

To post a test trigger instance

1. Locate your Amazon id, which is the same userId explained in the custom skill request session object.

2. With your Amazon id as the target, make a POST request by either using a REST client or the curl command to call the Routines Trigger Instance REST API.

For more details about posting a trigger instance, see Dispatch a trigger instance.

Important: The trigger.name and the trigger.parameters must match with what was provided in the SPI callback from Step 3.

The following example shows a trigger instance UNICAST body.

3. Verify that you get a 202 OK successful response.

4. In your Alexa app, in the When this happens section for you to build routines, verify that you see a trigger with the display title Order status changes .

Note: Alexa processes triggers as they come in. You can't schedule a trigger instance with a future time for delivery.

Step 5. Change the endpoint to the production endpoint

After you have tested your triggers and you are happy with the quality of your skill, you are ready to change the endpoint from the development endpoint to the production endpoint.

To change the endpoint to the production endpoint

1. In your skill manifest skill.json, update the endpoint to production to make sure the new endpoint change gets published.

Important: Update the endpoint to production before you submit the skill for certification.

2. To send your latest trigger definition, contact Amazon and ask to publish the skill to live.

For details about the production endpoint, see Production endpoint.

Step 6. Get your customers to use your trigger

After Amazon certifies your skill to enable you to send trigger instances on registered triggers, your customers can open their Alexa app, and set up routines by using this new trigger.

The Alexa app lists your new trigger under the same When this happens section where the built-in triggers are listed.

For more details, see Set Up an Alexa Routine.

Step 7: Send actual trigger instances through the REST API

Now you have set up your custom triggers for routines mechanism and ready to send trigger instances.

To send a trigger instance through the REST API

After an actual trigger instance occurs, send the trigger instance to the Routines Trigger Instance API production endpoint.

For details, see Dispatch a trigger instance. For details about obtaining the access token for calling the REST API, see Step 4.2 Get an access token with the curl command.

Show personalized options with dynamic parameters

To show personalized options, you can use the dynamic parameters feature. With dynamic parameters, you can show your customers triggers and parameters that are not predefined in the trigger definition file. Instead these parameters are returned through the SPI that your skill supports.

For example use cases, see Dynamic Parameters Examples.

Was this page helpful?

Provide feedback

Last updated: Nov 27, 2023