Triggers

Have a Coworker run work on its own, on a schedule, once at a set time, or when another system calls a web address.

For: A Coworker's Supervisor · Last updated

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 in the Triggers section of the Coworker's details page, in the main column below Connectors. Select its heading to open it; its closed row shows how many triggers there are. The section 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 Coworkers page with Details.

When there are no triggers, the section 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 section, scheduled runs do not fire, and webhook calls are refused, until it is approved.

Add a trigger#

  1. In the Triggers section, 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. Optionally, under Send results to Slack or Teams, choose where each run's final message is posted (see Send results to Slack or Teams).
  7. Select Add trigger. Select Cancel to close the form without saving. If anything is missing, a message appears under the field.

Send results to Slack or Teams#

When the Coworker is connected to Slack or Microsoft Teams, a trigger can post what the Coworker produces in a chat. Choose Send results to Slack or Teams on the trigger and pick one of:

  • Direct message to me — a private message to you in that chat app.
  • A channel (or, in Teams, a group chat) that the Coworker's app can post in.

Each time a run finishes, the Coworker's final message is posted there automatically, the way a chat reply is. It is the message as the Coworker wrote it, in that app's own formatting, with no extra wrapper. Nothing is posted when the run fails, is cancelled, or ends without a message, or when the Coworker decides the run needs no message (for example it only added a reaction). The Coworker does not have to do anything for this to happen, and during a run it can also post extra messages to the same place by sending to "default".

Things to know:

  • The Coworker must be invited to a channel before it can post there. In Slack, invite the app to the channel; the list shows the channels it is already in. In Teams, the list shows the channels and group chats where people have already used the Coworker. If a channel you expect is missing, invite or mention the Coworker there first.
  • A direct message needs your account linked to the chat app (see Chat with a Coworker in Slack and Teams). In Teams you also need to have sent the Coworker a message once. Until then the app is listed with a note saying what to do.
  • The trigger's results are posted with the permissions of the person who created the trigger, and a direct message goes to that person, even when someone else starts a run with Run now. If that person unlinks their account later, the direct message stops being delivered.
  • Choosing a destination needs no administrator setting. Choosing, changing and clearing it is recorded in the Audit tab.
  • If you also turned on notifications for the chat app in your own settings, you still get one message, not two, when the destination is your direct message in that app.
  • The run's final message is posted automatically, so you do not need to tell it to post. Write the task as what to produce, for example "Write a short good-morning message", rather than "Post a good-morning message". The Coworker may still send a brief progress note first.
  • Clear the choice to stop posting. Removing the Coworker's chat app also clears it.

You can also ask the Coworker to set this up for you. In a Slack or Teams chat, say what you want done later or on a schedule and that you want the result reported back, for example "Every Monday at 9, summarize last week's orders and post it here." The Coworker creates the trigger with the destination already chosen: here is the channel or chat you are in (in a direct message, your direct messages), and it can also message you directly or use a channel it finds for you. The same rules apply as above: the Coworker must be in that channel, and a direct message needs your account linked. The Coworker only does this when you ask to hear back in chat. If the destination cannot be set, it tells you why and no trigger is created.

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.

When a trigger posts its results to a chat, a line with a send icon says where, such as "Posts to #general (Slack)" or "Posts a direct message to Ada Lovelace (Slack)". Select Change beside it and choose another place, or Not sent to stop posting; it saves at once. A trigger with no destination shows Send results to Slack or Teams when the Coworker is connected to a chat app.

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, and so is setting, changing or clearing where a trigger sends its results. 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.