> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/assistants/triggers.md).

# Triggers

Let an assistant start work on its own, without anyone opening a chat. Configured on the **Triggers** tab of an assistant.

## What a trigger is for

An assistant normally waits for a question. A trigger lets it start by itself: at a set time, when another system sends it something, or when an e-mail is forwarded to it. The assistant then carries out the instruction you wrote, and the result is kept so you can review it.

One such independent piece of work is called a **run**. [Runs and the Cockpit](https://docs.artific.nl/en/for-administrators/assistants/runs.md) explains how to follow, check and manage runs.

Triggers suit work that recurs, or that starts with an event somewhere else:

* a weekly market briefing,
* processing the invoices that finance forwards,
* following up as soon as a campaign starts in your CRM.

## The three kinds of trigger

| Trigger       | Starts when                                                                                          | Typical use                                               |
| ------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Schedule**  | A set moment: daily, weekly, monthly, once, or a custom schedule.                                    | Recurring reports and checks.                             |
| **Webhook**   | Another system calls the trigger's own address. What it sends is passed to the assistant as context. | Reacting to events in a CRM, a form or your own software. |
| **Mail-hook** | An e-mail arrives at the trigger's own address.                                                      | Handling mail that a team forwards, such as invoices.     |

## Adding a trigger

1. Open the assistant's management area and choose the **Triggers** tab.
2. Choose **Add trigger** and pick **Schedule**, **Webhook** or **Mail-hook**.
3. Give it a **Name** that says what it does, such as *Weekly market briefing*.
4. Write the **Instruction for** the assistant: what it should do when the trigger fires. Write it the way you would ask a colleague.
5. Set the limits, and if you want, the criteria, human approval and notifications described below.
6. Choose **Create trigger**.

Every trigger in the list has its own on/off switch, so you can pause it without deleting it. The list also shows when a scheduled trigger runs next.

## Schedule

A schedule has three modes:

| Mode       | What you set                                                                                                            |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Repeat** | Daily, weekly or monthly, at a set time. Monthly runs on a date, or on a weekday such as the first Monday of the month. |
| **Once**   | A single date and time. The trigger switches itself off afterwards.                                                     |
| **Cron**   | Under **Advanced**: a cron expression for schedules the other modes cannot express.                                     |

Times are shown in a timezone, which you can **Change** per trigger. A monthly schedule set to a day that a shorter month does not have runs on that month's last day.

**Catch up on a missed run** makes a scheduled run that could not start run later after all, instead of being skipped.

A cron expression has five fields: minute, hour, day of the month, month and day of the week. There must be at least five minutes between two runs.

## Webhook

When you create the trigger, it gets its own **Webhook URL**. Give that address to the external system. As soon as something comes in there, a run starts and the content goes to the assistant as context.

This part is technical. If you are not the person who connects the external system, hand it to whoever does.

### Authentication

Every call has to prove it comes from the right system. Choose one of two methods under **Authentication**:

| Method                        | How it works                                                                                                                                                    |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Signature (HMAC)**          | The recommended method. The external system signs each call with a secret, so the platform can check both the sender and that the content was not altered.      |
| **Shared secret in a header** | The external system sends the secret itself with every call. Weaker: it does not prove the content arrived unchanged. Use it only for systems that cannot sign. |

The secret is one of your organisation's [secret keys](https://docs.artific.nl/en/for-administrators/tools/secret-keys.md). Pick an existing one under **Signing secret**, or choose **Generate new secret**. Calls without a valid signature are refused, and so are signed calls more than five minutes old. The trigger screen shows exactly what the external system has to send.

An optional `Idempotency-Key` header makes a repeated call within 24 hours return the first run instead of starting another. Use it when the external system may send the same event twice.

### Variables

Instead of passing the whole incoming message to the assistant, you can pick out the fields you need.

| Field        | What it does                                                                            |
| ------------ | --------------------------------------------------------------------------------------- |
| **Name**     | What you call the value in the instruction, used as `{{name}}`.                         |
| **Field**    | Where the value sits in the incoming data, as a JSON pointer such as `/invoice/number`. |
| **Required** | Whether a call without this value is refused.                                           |

A value always goes into the instruction as quoted data, never as an instruction.

{% hint style="warning" %}
A variable with an empty field passes the entire incoming body on. Everything the caller sends then reaches the assistant's instruction, so anyone who can call the address writes part of it. Pick out the fields you need wherever you can.
{% endhint %}

## Mail-hook

When you create the trigger, it gets its own **Forwarding address**. Forward an e-mail to that address and the assistant starts a run with the mail as its input. Attachments come along as files.

In the instruction, `{{subject}}` and `{{body_text}}` insert the subject and the text of the e-mail.

**Allowed senders** decides who may start a run, one entry per line:

* a full address, such as `finance@example.com`,
* or `@example.com` for everyone at that domain.

Mail from anyone else starts nothing, and neither does mail that fails the sender checks that prove an e-mail really comes from its domain. Automatic replies and bounces are ignored. The trigger shows how many e-mails were ignored, so you can see when a colleague is forwarding from an address that is not on the list.

## Instruction, criteria and limits

### Instruction

The instruction is the task for this trigger, on top of the assistant's own [instructions](https://docs.artific.nl/en/for-administrators/assistants/settings.md). Say what to do, which sources to use, what the result should look like and where it should go. Vague tasks produce vague runs.

### Criteria for a successful run

Optional, and worth filling in. When a run finishes, the assistant checks the result against these criteria. A run that does not meet them fails.

> *The amount matches the order. The customer is addressed by name.*

Criteria turn "the run finished" into "the run did what it should". They are also what makes a failed run easy to spot in the [Cockpit](https://docs.artific.nl/en/for-administrators/assistants/runs.md).

### Limits

| Setting                                | What it does                                                                                                                           |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Time limit per run (minutes)**       | A run that works longer stops as failed.                                                                                               |
| **Cost limit per run ($)**             | A run that costs more stops as failed.                                                                                                 |
| **Maximum number of actions in a run** | An action is a step in which the assistant uses a tool. At this number the run stops, wraps up with what it has, and counts as failed. |

Each has an upper bound. Together they make sure a run can never carry on indefinitely. [Budgets](https://docs.artific.nl/en/for-administrators/organization/budgets.md) add a monthly ceiling on top.

## Human approval

**Human approval** decides when the assistant involves a person before carrying on.

Switch it on and describe the cases in plain language under **When should the assistant involve you?**:

> *Ask before sending e-mail to a customer. If the order number is missing, ask me for it. Internal e-mail to @example.com can go out without asking.*

Before each action, and whenever information is missing, the assistant decides from this instruction whether to ask for approval or ask a question.

| Situation                                 | What happens                                                                                                                                                                     |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Instruction left empty                    | The assistant asks for approval before any action that changes something outside the conversation: sending, creating, updating or deleting. It asks when information is missing. |
| Knowledge base searches                   | Never need approval.                                                                                                                                                             |
| A connector that needs someone to sign in | Always asks, whatever the instruction says.                                                                                                                                      |
| Sub-agents                                | Never ask. Their actions are not covered by this instruction.                                                                                                                    |
| **Human approval** switched off           | Runs never wait for a person.                                                                                                                                                    |

Approving and answering always happen in the platform. What that looks like for the person asked is described in [When an assistant needs you](https://docs.artific.nl/en/for-everyone/assistants/waiting-on-you.md).

{% hint style="warning" %}
The assistant follows the approval instruction as well as it understands it. Describe the cases clearly, and agree them with whoever owns the process, especially when the assistant sends e-mail or changes data in other systems.
{% endhint %}

## Notifications

Under **Notifications · e-mail per status**, choose who receives an e-mail for each status. Recipients can be users or user groups.

| Status              | Sent when                      |
| ------------------- | ------------------------------ |
| **Started**         | The run has started.           |
| **Completed**       | The result has been delivered. |
| **Needs attention** | Approval or input is needed.   |
| **Failed**          | The run stopped with an error. |

A status without recipients sends no e-mail. Every pause for approval or input sends one e-mail, and with **Reminder** you set after how many hours a single reminder goes out if nobody has responded.

Under **Webhooks** you can also send the events of this trigger to other systems. Those webhooks are set up under [Notification channels](https://docs.artific.nl/en/for-administrators/organization/notification-channels.md).

## Act as

Runs act as the assistant's own trigger account, which is created and kept up to date automatically. Under **Advanced** you can choose another [service account](https://docs.artific.nl/en/for-administrators/access/service-accounts.md) instead, but only do that when runs need its permissions.

If the chosen service account is disabled or removed, runs fail until you enable it or choose another.

## Run now

**Run now** starts the trigger straight away, without waiting for its moment. Fill in the values the instruction uses, and the run starts as if the trigger had fired. Use it to test a new instruction before you rely on the schedule.

A trigger runs one run at a time. While a run is still in progress, a new one does not start.

## Connected accounts

When an assistant uses a connector that works with a person's own account, a run acts through the connector account of the person who connected it. **Connected accounts** on the trigger shows whose account that is and since when. **Revoke** stops later runs from using it.

## Deleting a trigger

**Delete** stops the trigger and removes it. Runs it already started keep their history.

## Setting up a trigger well

* **Start with human approval on.** Loosen it once you have seen a number of runs go right.
* **Test with Run now** before you switch the schedule on.
* **Write criteria.** Without them, a run that finished but did the wrong thing still looks successful.
* **Start with tight limits** and raise them when runs need more room.
* **Check the first runs step by step** in the [Cockpit](https://docs.artific.nl/en/for-administrators/assistants/runs.md) before you leave the trigger to itself.
