> 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: About Custom Triggers

## Article: About Custom Triggers

## Article Link: https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/automations/about-custom-triggers.md

## Article Content:

# About Custom Triggers

When you create a new [automation](https://support.wix.com/en/article/wix-automations-about-the-new-automations-builder) on your site, you must select a trigger that causes the automation to run. A trigger is an event that occurs on a site and gets reported to Wix.

An automation only runs when the trigger occurs. For example, if you select the **Member logs in** trigger, your automation runs when a member logs in. Most triggers are based on similar business logic, like payment information or contact management.

However, you may want to run your automation when an event occurs that isn't defined by existing triggers. Examples include:

- Creating a new contact when a site visitor clicks a certain button.
- Send a chat message offering help when a member inputs an invalid value into a text input field.
- Send a coupon if a visitor is on your site for a certain period of time.

With the [Custom Trigger API](https://dev.wix.com/docs/sdk/backend-modules/automations/triggers/custom-trigger/introduction.md), you can run an automation for any event that occurs by triggering the automation from your code. This gives you greater control and flexibility over when your automations run.

## Supported IDEs

Once you select the code trigger in the automation builder, you can write your code with the following IDEs:

- The [editor](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/developer-environments/editors/wix-studio-working-with-the-code-panel.md) (Wix Studio and Wix Editor)
- The [Wix IDE](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/developer-environments/ides/wix-studio-about-the-wix-ide.md) (Wix Studio)
- Your [local IDE](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/developer-environments/ides/git-integration/about-git-integration-with-wix-cli.md) (Wix Studio and Wix Editor)

## Trigger configuration

There are 2 parts to the trigger configuration:

- [Trigger ID](#trigger-id)
- [Payload schema](#payload-schema)

### Trigger ID

When you select the **Velo code trigger** as your automation trigger, Wix generates a unique trigger ID. When you call [`runTrigger()`](https://dev.wix.com/docs/sdk/backend-modules/automations/triggers/custom-trigger/run-trigger.md), you need to specify the trigger ID. The method then runs the automation associated with the ID. You can run automations from anywhere in your site code, simply by calling `runTrigger()` with the relevant ID.

### Payload schema

In addition to the ID, you can optionally define a payload schema for the trigger to specify when calling `runTrigger()`. The structure of the payload schema is generated from sample data that you enter when you configure the trigger. For example, if you enter sample data like this:

```javascript
{
 "firstName": "Ronald",
 "id": "ed8fa327-f821-4c30-b336-1784be278541",
 "age": 50,
 "contactEmail": "ronald@example.com",
 "favoriteFoods": ["hamburgers", "French toast", "chicken nuggets"]
}
```

Your payload schema will have a structure like this:

```javascript
{
  firstName: string,
  id: string (uuid),
  age: number,
  contactEmail: string (email),
  favoriteFoods: [ string ]
}
```

The method's `payload` field is optional even if you define a payload schema. If you do specify a payload, you can't specify a payload with fields that aren't defined in the schema but you can omit fields. Any fields you include in the payload must match the key and type defined in the schema. 

For example, if your payload structure looks like the one above, you can pass the following payloads to `runTrigger()`:

```javascript
$w("#myButton1").onClick(async () => {
  const payload = {
    firstName: "Amy",
    id: "5d696ec4-0933-4b4d-9acd-50b316717ff2",
    age: 27,
    contactEmail: "amy@email.com",
    favoriteFoods: ["pizza", "hamburger"],
  };
  await runTrigger(payload);
});

$w("#myButton2").onClick(async () => {
  const payload = {
    firstName: "Josh",
    id: "46123fae-6b6f-4edb-98f1-50f0eaded97e",
    contactEmail: "josh@email.com",
  };
  await runTrigger(payload);
});

$w("#myButton3").onClick(async () => {
  const payload = {};
  await runTrigger(payload);
});
```

Some actions may require certain payload fields to be specified. For example, if subsequent actions need to access contact data, be sure to pass the contact ID field.

#### Contact data in the payload schema

If your payload schema contains 1 or more UUID fields, you can mark one of those fields as a contact ID. When the payload is passed to `runTrigger()`, Wix looks up the ID in the contact ID field. If the ID corresponds to an existing contact, Wix retrieves the contact’s data and attaches that data to the payload. The data can then be passed to any subsequent actions.

> **Note:** If the ID corresponds to a new contact, you can save the contact data by executing the **Create a Contact** action after the trigger.
<!-- this needs to be checked -->

## Common errors

Here are some common errors you might encounter and their causes:

| Error message            | Cause                       | 
| ------------------------ | --------------------------- |
| Automation not found         | No automation is found for the trigger ID passed to `runTrigger()`. This may be because the automation was deleted.       |
| This automation can only be executed within its designated application | This only applies to preinstalled automations when an app other than the one that created the automation tries to run it. |

## See also

- [Add a Custom Trigger](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/automations/add-a-custom-trigger.md)
- [Custom Trigger SDK](https://dev.wix.com/docs/sdk/backend-modules/automations/triggers/custom-trigger/introduction.md)
- [About Automations](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/automations/about-automations.md)