> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Add a Trigger to Your App

## Article: Add a Trigger to Your App

## Article Link: https://dev.wix.com/docs/api-reference/business-management/automations/triggers/add-a-trigger-to-your-app.md

## Article Content:

# Add a Trigger to Your App

A trigger is an event that causes an automation to run.

To make an event a trigger, you need to do two things:

- Add a trigger extension in the [app dashboard](https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fautomations-dev-center). As part of this extension, you configure a [payload schema](https://dev.wix.com/docs/rest/business-management/automations/triggers/the-trigger-payload-schema.md) and other settings for your trigger.

- In your app code, [report the event](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/about-triggers.md) to Wix Automations.

This article walks you through how to add and configure the trigger extension. Once you complete this process and publish your app, any user who installs your app will see this trigger in the [Automations Builder](https://support.wix.com/en/article/wix-automations-creating-an-automation-with-the-new-builder) on their site.

## Before you begin

- Familiarize yourself with [triggers](https://dev.wix.com/docs/rest/business-management/automations/triggers/about-triggers.md).
- Make sure you implement your app using [OAuth with app instance authentication](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/authenticate-using-oauth.md). This is required because only your app can report and cancel your trigger's events.

## Step 1 | Set up the trigger

In this step, you'll create a new trigger and configure its name and key.

The trigger key identifies your trigger when you [report and cancel events](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/reporting-and-canceling-events.md). It won't be visible to users but it is visible to you, so choose a key that's meaningful to you. After you publish your app, the trigger key can't be changed.

1. In your app's [Automations](https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Fautomations-dev-center) page, click **Create New > Trigger**.

   ![Create new trigger](https://wixmp-833713b177cebf373f611808.wixmp.com/images/4092f428658f0ee0cb8b3b9691343b1e.png)

2. In the new page that opens, set your **Trigger name**.

   Users see the trigger name when they select a trigger for use on their site, so it’s important to give it a good name. This helps users understand what kind of events activate your trigger. To keep your trigger name user-friendly and consistent with other triggers, we recommend following these best practices:

   - Use passive voice.

   - Keep the name singular.

   - Use sentence case, and don't end with a period.

   - Make sure it can't be confused with another app or trigger. For example, "Reservation made" can mean several different types of reservations, so "Restaurant reservation made" is a less ambiguous name.

   Some examples of good trigger names are:

   - **Customer registered for session**

   - **Interest form submitted**

   - **Gym member approved for discount**

3. Create a **Trigger key** using the suggested _<app_name>_-_<trigger_name>_ format. The trigger key must:

   - Start with a letter or number.
   - Contain only lowercase letters, numbers, hyphens, and underscores.
   - Not be the same as another trigger key in your app.

   ![Trigger name and key](https://wixmp-833713b177cebf373f611808.wixmp.com/images/6bb97ef74138cdd13aa782d7a1617428.png)

## Step 2 | Configure the payload schema

Now that you've created your trigger, you need to create a payload schema for it. This step walks you through the process of generating your payload schema. For more in-depth information on the schema specifications, see [The Payload Schema](https://dev.wix.com/docs/rest/business-management/automations/triggers/the-trigger-payload-schema.md).

You’re required to create the schema because it tells Wix exactly what data it receives when your app reports the event. This impacts the actions available to users (for example, whether they can use contact-based actions or not). Wix also presents trigger settings to the user based on the payload properties, such as whether the user can [schedule the trigger](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/about-triggers.md).

Before you continue, you'll need a sample of the expected payload as a JSON object. The JSON object will be used to create the initial version of your payload schema, which you can build out from there.

> **Note**: To learn about all the available options, include these fields in the sample JSON object:
>
> - String in UUID format.
> - String in date-time format.
>
> If your final payload does not require these fields, you can remove them later.

At the end of this step, you'll have a fully configured payload schema.

1. To create the initial draft of a schema from your sample payload data, click **Convert from Payload**.

   ![Convert from payload](https://wixmp-833713b177cebf373f611808.wixmp.com/images/3157144fe9f5f8084d4033f76d8d140f.png)

2. In the **Convert a payload to a schema** modal, paste your sample JSON object, and click **Convert to Schema**. The modal closes and your schema is generated in the main textbox.

   ![Convert payload to schema](https://wixmp-833713b177cebf373f611808.wixmp.com/images/0eaaa93793e5d5bc3bbd047b48a8095b.png)

3. Click **Process Schema**. This validates the schema changes and makes the schema fields available to the remaining trigger configuration.

4. To further configure your schema, click **Manage Schema Properties** and then click the **Developer** tab. The **Manage schema properties** modal provides you with a UI to configure certain settings for each property in your schema. This includes:

   - **Display name:** The display name is directly connected to the `title` key found in each property, and sets the field label that the user sees on in their dashboard. You have the choice to edit it here or in the schema.

   - **Required:** You can mark a field as required by checking the box. If you mark a field as required here, it will automatically be added to the `required` array.

   - **Example**: You can add or edit entries in the `examples` array of a property. The schema is updated automatically with your changes.

   - **Description**: You can write a description of the schema property here and the `description` key will be added to your schema, with the description you write as its string value. If you already have a `description` key, you can edit its value here.

     ![Manage schema properties modal](https://wixmp-833713b177cebf373f611808.wixmp.com/images/406758b614e71c8db35235ff8ced1ae6.png)

5. When you're finished, click **Update Schema**. The modal closes and your schema is updated.

Your schema now contains all the fields in your sample JSON, the display names are set, and the relevant fields are marked as required. In the next steps, you'll continue to refine and finalize the schema.

## Step 3 | Review and fix the schema

In the previous step, you generated a JSON schema from a sample payload. However, the payload schema may not be a true representation of the schema you intended. For example, data types and string formats are inferred from data you provided in the sample payload, but some of those details could be incorrect.

In this step, review the generated payload schema and revise as needed. For a complete payload schema spec, see [Payload Schema](https://dev.wix.com/docs/rest/business-management/automations/triggers/the-trigger-payload-schema.md). Continue when you're happy with your schema.

## Step 4 | Additional configuration

In this step, you'll add some additional configuration to your trigger. All the configuration options shown here are optional, and your trigger will work without them. However, it may have limited functionality that reduces its usefulness to users. You can read more about the different configuration options in [About Triggers](https://dev.wix.com/docs/rest/business-management/automations/triggers/about-triggers.md).

### **Add contact data to the payload**

You can select one payload property to connect to a contact ID. This tells Wix to retrieve the contact ID and its associated data and attach it to the payload. If you don’t connect a contact ID, users won’t be able to use your trigger with contact-based actions like **Send an email**.

The payload property you connect must be of type `"string"` and have a `“uuid”` format.

To connect a property to a contact ID:

1. Under **Contact enrichment & scheduled events**, select **Connect ContactID to enrich the trigger with contact details**. A dropdown menu appears with a list of payload properties that meet the data type requirements and are available to connect.

   ![Connect property to contactId](https://wixmp-833713b177cebf373f611808.wixmp.com/images/3cd6042126c05922b61de0702167e737.png)

2. Select the relevant field from the list. This adds the `"identityType": "contact"` key-value pair to the connected field in the schema.

### Allow scheduled events with predefined date & time

By default, users can set an automation to run either immediately when an event is reported or after a delay. If you allow scheduled triggers, however, users also have the option to run the automation before the event. This is useful if your trigger will be used to send reminders for appointments or other scheduled events.

This option is available only for fields where the type is `"string"` and the format is `"date-time"`.

To specify a scheduled event field:

1. Under **Contact enrichment & scheduled events**, click **Allow scheduled events with predefined date & time**. A list containing the available fields is displayed.

   ![Allow scheduled events with predefined date & time](https://wixmp-833713b177cebf373f611808.wixmp.com/images/faf28c223ca1c0a50245099203ff23d3.png)

2. Select the relevant field from the list. This adds the `"futureDate": true` key-value pair to the selected field in the schema.

### Add filter fields to the trigger

Every time an event occurs in your service, your app reports it to Wix. However, a user who has applied your trigger might not want to run their automations on every single event occurrence. Adding [filter fields](https://dev.wix.com/docs/rest/business-management/automations/triggers/about-triggers.md#filter-fields) to your payload properties allows users to filter reported events based on whether certain conditions are met.

When you create a filter field on a payload property, the user can set criteria for that property when they set up the trigger in their site dashboard. For example, a user might only want to run a **Product purchased** automation when a customer makes a purchase of more than $50. You can allow this by adding a filter field on a number property such as price.

To get started, click **Create Filter Field**, select the filter field type you want to add, and fill in the required information.

![Create filter fields](https://wixmp-833713b177cebf373f611808.wixmp.com/images/905d8f196d48732362ad146590a16c8c.png)

<!--The information needed for each type of filter field is different, so see [Filter Fields](https://dev.wix.com/docs/rest/business-management/automations/triggers/filter-fields.md) for the full list of options.-->

When you're finished configuring your filter field, click **Apply** to save your settings.

## Step 5 | Provide translations for trigger text

This step is optional. You can provide translations for some written elements of your trigger into different languages to make it more accessible to audiences in other languages.

1. In the app dashboard, navigate to [Translations](https://dev.wix.com/app-selector?title=Select+an+App&primaryButtonText=Select+Site&actionUrl=https%3A%2F%2Fdev.wix.com%2Fapps%2F%7BappId%7D%2Ftranslations-dev-center).

2. Click **Add Language** to open the **Add languages** modal.

3. Select the languages you want to provide, and click **Add**.

4. Find the triggers whose strings you want to translate, and click **Translate**. The translation editing page is displayed.

5. Enter the translation for each string, and then click **Save**.

6. Activate each trigger whose translations you want visible for users.

## Step 6 | Test the trigger

In this step you'll install your trigger on a test site, create a test automation, and report a test event. Note that, because only the app that created the trigger can report its events, you must run the test call from your servers using an OAuth token.

To test your trigger:

1. If you haven't saved your trigger already, click **Save & Close** to save it now.

2. Install your app on a [test site](https://dev.wix.com/docs/build-apps/launch-your-app/app-distribution/test-your-app/test-your-app-on-a-premium-site.md).

3. In the site dashboard, [create an automation](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Ftriggers/rules). Configure the automation as follows:

   - **Trigger**: Use your new trigger and configure accordingly.

   - **Action**: Use **Send an email**, and use these settings:

     - When editing the email template, click **Add Dynamic Value** in the left pane to include placeholders for your payload properties.

     - In **Set recipients**, select **Include additional recipients**, select **Add Recipients > Collaborator roles**, and then select **Owner**. Click **Save** to return to the automation configuration screen.

       ![Select Roles Modal](https://wixmp-833713b177cebf373f611808.wixmp.com/images/fce1c7d57d0e766a1dbabf8d22a2e4f4.png)

4. To save your automation, complete all the required information and click **Activate**.

5. [Create](https://dev.wix.com/docs/rest/app-management/oauth-2/create-access-token.md) or [refresh](https://dev.wix.com/docs/rest/app-management/oauth-2/refresh-an-access-token.md) an OAuth access token for the test site, depending on the OAuth method you used.

6. Send a test payload to [Report Event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md).

If you completed this task successfully, you'll receive an email populated with the payload values.