Trigger Definition

To implement a custom trigger, you must provide at least one trigger definition file in your routines skill package to represent your custom trigger.

In your routines skill package, use the /skill-package/routines/triggers/ directory to hold trigger definition files. Only Alexa skills with the type routines can understand trigger definitions.

The following skill package directory shows a skill package that contains a trigger that supports two locales. Items marked with (new) indicate that they are for the routines skill type only.

The trigger definition file is a JSON file. Add your trigger definition files in the /skill-package/routines/triggers/{some-trigger-name}/ directory for each trigger type. The file name for your trigger definition must match with the four letter locale code supported in Alexa skills. For example, use the en-US.json file name to represent a trigger definition in US english. All locale files must share the same name field. Only their display.title, display.iconUrl, and display.description fields might differ.

The following JSON file shows a trigger definition template.

The following JSON file shows a UNICAST trigger definition example.

The following JSON file shows a MULTICAST trigger definition example.

Trigger definition

The following table shows details about the trigger definition for your JSON file.

Field Description Type Required

name

Name that identifies the custom trigger in your skill. This name is case sensitive and accepts from one to a maximum of 50 alphanumeric characters.

String

Yes

display

Trigger display object. For more details, see display object.

Object

Yes

parameters

A list of objects that define the parameters for your trigger. For more details, see parameters object.

Array of objects

Yes

delivery

Type of trigger. Acceptable values are: UNICAST, MULTICAST. The UNICAST delivery sends the trigger event to one customer only for each API request. The MULTICAST delivery sends a shared trigger event to multiple customers for each API request.

String

Yes

accountLinkingRequired

Indicates whether your skill requires account linking. Acceptable values are: REQUIRED, NOT_REQUIRED. The default setting is NOT_REQUIRED. If you set the value to REQUIRED, make sure that your skill has account linking implemented and enabled. For details, see Add Account Linking to Your Alexa Skill.

String

No

displayCategories

Values that help categorize your trigger. Accepted values are: ASTROLOGY, BUSINESS_AND_FINANCE, CONNECTED_CAR, ENTERTAINMENT, HEALTH_AND_WELLNESS, NEWS, RESTAURANT, SHOPPING, SOCIAL_NETWORKING, SPORTS, TAXI_AND_RIDESHARING, WEATHER.

Array of strings

Yes

keywords

List of search terms that your customer can use to search the trigger. Keywords can be different for different locales.

Array of strings

Yes

Display object

Use the display object to describe the trigger details that you want to display in the Alexa app. You can create the display object for each locale.

Field Description Type Required

title

Title for the trigger in the Alexa app. You can localize the title for different locales.

String

Yes

description

Description for the trigger in the Alexa app. The description field contains more details about the trigger, while the title field provides a short summary of the trigger. You can localize the description for different locales.

String

No

iconUrl

Public web address to get the trigger icon. You can localize the icon for different locales.

String

No

Parameters object

Use parameters to define a list of parameters for your trigger. Your customers use trigger parameters when they create or update a trigger. Routines require a defined list of parameters to construct a trigger detail page and render valid trigger parameters. How you order the parameters list determines their order on the rendered page.

Field Description Type Required

name

Name of the trigger parameter in the trigger creation request data object.

String

Yes

schema

The parameter schema including its type. For more details, see schema object.

Object

Yes

display

Information about the title, description, and icon URL for the custom trigger. For more details, see display object.

Object

Yes

Schema object

Use the schema object inside the parameters object to specify the schema details. Acceptable value: enum.

Field Description Type Required

type

Type of the schema. Acceptable value: enum. For details, see enum type schema object.

String

Yes

Enum type schema object

The enum type schema accepts a list of enum value objects.

Field Description Type Required

type

For the enum type schema, set this field to enum.

String

Yes

values

Available enum values and their display metadata. See enum value object.

Array of enum value objects

Yes

Enum value object

The enum value object lists distinct values.

Field Description Type Required

value

Distinct enumeration value of the enum set. This is the value of the enum data in the trigger creation request data.

String

Yes

display

Trigger display object. For more details, see display object.

Object

Yes

Best practices for trigger icons, descriptions, and titles

  • Your icons must meet the following requirements:

    • PNG file format
    • 512 x 512 pixels in size
    • Transparent background
    • Visible on both light (#FFFFFF) and dark (#010B13) mode backgrounds

  • You should have icons for all options in an enum list, or for none of them. The same rule applies to descriptions.

  • The name field and display.title are different. The display.title is what your customer sees, therefore you should make sure that your display.title reflects the actual meaning of your trigger.

Example icons

Icon with a transparent background

Icon example with no background.

Icon clearly visible on both light and dark backgrounds

Icon shown with white and black background.
Was this page helpful?

Last updated: Oct 30, 2025