Triggers

A trigger lets a Coworker do a piece of work without anyone starting a chat. You give it an instruction, and the Coworker carries it out each time the trigger fires.

Triggers are managed from the Triggers card on the Coworker's details page. The card is shown to people who can work with the Coworker. Its Supervisor sees every trigger on it; everyone else sees only the triggers they created. Open the details page from the roster with Details.

When there are no triggers, the card shows a centered empty state with an Add trigger button. While a Coworker is awaiting approval (see Proposed Coworkers), its details page has no Triggers card, scheduled runs do not fire, and webhook calls are refused, until it is approved.

Add a trigger#

1. On the Triggers card, select Add trigger.
2. Under How it starts, choose On a schedule or When another app calls it.
3. For On a schedule, choose Repeats:
   • Every day, Every weekday (Monday to Friday) — choose a time and time zone.
   • Every week — select one or more days, choose a time and time zone.
   • Every month — pick a day of the month (1 to 31), choose a time and time zone. Months without the chosen day are skipped.
   • Does not repeat — choose a date.
   • Custom (cron expression) — enter a five-field cron expression. This option is for developers. A summary box below the fields describes the schedule in plain language, such as "Runs every weekday at 9:00 AM Eastern Time."
4. For When another app calls it, there is nothing else to fill in. A unique web address is created when you add the trigger.
5. In What should [Coworker name] do each time?, write the instruction the Coworker will carry out. It is required.
6. Select Add trigger. Select Cancel to close the form without saving. If anything is missing, a message appears under the field.

Reading the list#

Each trigger shows its schedule on the first line with an Active switch. Below that are label and value rows:

• Asks — the Coworker's name and the instruction you wrote.
• Runs as — the person the trigger runs on behalf of (the person who created it).
• Next run — when the trigger will next fire, shown in the trigger's own time zone. A paused trigger shows "None while paused."
• Last run — when the trigger last fired, also in the trigger's time zone.

All dates and times on a trigger are shown in the time zone chosen when it was created, so they always agree with the schedule.

A custom cron expression that cannot be described in a sentence shows "Custom schedule" with the expression in a code box.

What you can do with a trigger#

• Run now runs the trigger immediately, whatever its schedule.
• The Active switch pauses or resumes the trigger. It saves at once.
• Delete removes it after you confirm in the Delete this trigger? dialog. Select Delete trigger. The confirm button is red. This cannot be undone.
• Recent runs opens the latest runs; Hide runs closes the list.

A one-time trigger runs once and then shows as paused.

Runs#

Each time a trigger fires, the Coworker starts a conversation titled "Trigger:" followed by the beginning of your instruction. Select Recent runs on the trigger to see the latest runs. Each run shows a status pill — Succeeded, Failed, or Running — next to the date and time it ran, in the trigger's time zone. A failed run shows its error on the following line. Select a run to open its conversation in Chat.

The list shows the latest five runs. Select Show more to see more. When the trigger has not run, the list reads "This trigger hasn't run."

Trigger runs are kept apart from your own chats and do not appear in your conversation list. A run started by a schedule is attributed to the person who created the schedule. A run started with Run now, or by a webhook call, is attributed to the person who started it.

When a scheduled or one-time run creates a document, the document belongs to the person who created the trigger, and its history shows the Coworker as the author on that person's behalf. If that person has left, been disabled, or can no longer use the Coworker, the run still happens, but it cannot create or change documents.

Audit#

Creating, activating, pausing, deleting, and manually running a trigger are recorded in the Audit tab. Rotating a webhook trigger's key is also recorded. The Audit tab shows the Coworker's name and trigger type as the target. Filter by Triggers to see only trigger events.

Webhook triggers#

A webhook trigger shows its web address in a field, with Copy and Regenerate URL buttons. Give the address to the other system that should start the work.

Calls to the address must carry the personal API key of someone who is allowed to chat with the Coworker. Create and manage your key under Settings in My API keys. A call with a missing or invalid key is refused. A call to a paused trigger is refused too.

To replace the address, select Regenerate URL and confirm in the Regenerate this webhook URL? dialog. The old address stops working immediately, and any system using it needs the new one.