A bot works by itself. A trigger starts its work: every weekday at 8:30, once tomorrow at 9, or when something happens, like an email to its address or a webhook. It works with the integrations you give it, does what you said it should do, and tells you as its Notifications say. Routines you made before are bots now: each kept its time, its trigger, and its address.
Decisions, the button at the top of the sidebar, gathers everything waiting for you, from your chats and your bots alike, with the one count. Under it, switch from Chats to Bots to see your bots and the ones shared with you: those that need you first (decisions waiting for you, or a run that failed), then the rest, most recently busy first, each saying how many decisions wait for you in it, that it failed, that it's paused, or when it runs next. A dot on Bots says one of them needs you. The sidebar stays on Bots until you switch back. The card at the top of Bots opens the Bots page: Needs you, then Working, then Quiet, one row per bot with its face, a line on what it's doing, and its state, as they happen. A bot's own page opens on how it works, in the same three parts you made it with, When, Uses, and Does, then what waits for you in it, and its Runs: every run, newest first, a thread with someone outside being one run that keeps going, filtered by what waits, what's with a person, or what failed. Setup changes each part, each trigger opening in place under When; Delete is in the ⋯ menu beside Pause. Start one with New bot, from a recipe, a bot made for one job that you can change as you set it up, or from nothing. Most recipes work with whichever tool of a kind you use: "Any CRM" under a recipe, with the logos of the CRMs it works with, means the bot is set up with the one you connected, its instructions naming it. Where your tool can, it starts the bot when something happens: some on their own, others once you paste the bot's address into the tool, which the page after setup shows. Where it can't, the bot checks it on a schedule instead, every hour for most, and its setup says so. The recipes offered first are picked for you, from the services you connected, what you do (if you said, on your first new chat or in Settings ▸ Profile), and the services you use most, and each says why; All recipes lists every one.
The quickest way is to say it: New bot opens on What should your bot do?. Write what it should do and when, like "When a deal in HubSpot goes untouched for a week, draft a follow-up in Gmail", and send it. It starts a chat, like any other in your list, where the assistant proposes the bot on a card with When, Uses, and Does. Say what to change ("make it 8:00 and skip Fridays") and the card follows. Press Try it and it runs, changing nothing; if it needs a service you haven't connected, the card asks for that one first. Edit details opens the whole form. Nothing is made until you press Make bot. Every bot's Setup has the same chat: ask it for a change, and the change shows on the form and waits for you to approve it.
Or start from a recipe: under the sentence, New bot shows a team, such as Chief of staff or Bookkeeper, each with three jobs. Press a job for its card, the same as any recipe's. All beside a role, or All recipes under the team, lists the rest.
Making one asks three things, the same three a bot's page shows once it's made:
- When: what starts the bot. A recipe for any tool of a kind asks for your tool first, right here: Your issue tracker with GitHub, Linear, Jira, and the rest to pick from, the one you connected already picked. Picking another changes what follows in place: what starts it, the services it uses, and its instructions while they're still the recipe's words (yours stay as you wrote them). Then the app and what in it starts the bot, in plain words: On a schedule, GitHub (an issue opened, a pull request merged, a review requested from you...), From any app, Slack or Discord (mentions of the app in channels you pick, or every message there), and more. Search finds the rest. An app that needs one of your connections says so, with Connect right there. On GitHub, where an owner or admin installed the Chat with Work GitHub App, owners and admins choose As the GitHub App (it answers in the repositories you pick, as chat-with-work[bot], and it's shared in a project) or As you (it reads with your GitHub connection), each with its settings right there. Pick repositories from a list you search, or type owner/name. When I ask starts it only when you press Run now: a bot you describe without saying when starts this way.
- Uses: what it works with, as you. A recipe's other tools come first, each with your choice of tool (Your mailbox: Gmail or Outlook), then Also use another service for anything else: tick the ones you connected, or press Connect on any other. Connecting signs you in to it and brings you back to your half-made bot with everything you filled in kept. Changes in your connected services says whether what it would change in them asks you first (the default) or is made. Code lets it run code, Web search lets it search the web where your organization allows it, and, as the GitHub App, Writes code on GitHub lets it make its own branches and draft pull requests.
- Does: What should it do? Say what it does each time it starts, where it looks, and what it leaves to you. It's the one place that says what the bot does: every run reads it.
Name it. More settings holds who sees it, its monthly cap, and when it tells you.
Before you make it, Try it (on the card, or under Does on the form) runs it once as a try: on the latest event its app has, read with your connection, or a sample of what the app sends, with only the services you ticked. For a check by a small model, the try runs one check first to find something real, which costs about 1 to 2 credits, as the app's panel says. Nothing changes: whatever it would change shows as the approval it would ask you for, and none of them can be approved. What it found shows right there. To change the bot, say how in the composer under the try, then press Try again. Your tries open from the card, or from the bot's page once it's made. A try started from the form with no chat stays in your chats until you do. A try spends credits like a chat.
Try it waits for what the bot can't work without, and says so: "Needs HubSpot", with Connect. On a recipe, Tools swaps it for another of its kind, or a browser or commands on your computer where those can do the job. What a recipe can go without, like a CRM for Prospect finder, can be set to None, and the try still runs.
Who sees it
- Only you: a bot of yours works as you, on your credits and within any cap an admin set for you. Its runs are yours, and only you see the bot.
- A project: owners and admins can share a bot in a project. Everyone on the project sees it and reads its conversations, it has a monthly cap of its own, and the people who watch it approve what it waits on.
Triggers
A bot starts at a time, when something happens in an app you connected, or, for a bot shared in a project, when someone outside writes to it: through its API, a Chatwoot inbox, Slack or Discord channels, or GitHub through the Chat with Work GitHub App. Add one under When on the bot's Setup. Triggers says what each kind hears and how to set it up.
What a bot does is said in one place, What should it do?: its triggers only say when, and each run follows those words, knowing which trigger started it. A time starts a new conversation each run; an event can start a new one each time, or join the conversation of related ones (the same issue, the same email thread). Filters (Only when…) keep the noise out before a run starts, for free: for example, only mail whose subject contains "invoice". A trigger, opened under When on the bot's Setup, shows what it heard lately, what came of each, and what the latest one said, as the run reads it.
Integrations
What a bot works with, and what it may change without you, are set under Uses on its Setup. A bot's integrations and permissions says what each one reaches, what it costs, and when it asks first.
When it tells you
A bot's Notifications say when you hear of a run:
- When it needs me (the default): you hear when a run finds something worth your time, waits for your approval, or couldn't finish. Its instructions decide what counts ("tell me only if an invoice is more than 30 days overdue").
- Every run: you hear about every run's answer, like a morning report.
- Without Notifications, you hear nothing, and runs stay on the bot's page. If a trigger pauses itself, you still hear.
Each run is titled by its bot and when it ran ("Issue triage · today 09:00"), and opens with what started it: "Started at 09:00", or the event, like an issue opened on GitHub, with who sent it and what it's about. A bot's runs and conversations stay with the bot, out of your chat list: you find them under Bots in the sidebar, where the bot's row lights up while you're in one of its chats, on the bot's page, and in Decisions, and what it tells you opens them. Asking something in one brings it into your chats like any chat. Runs that found nothing show faint on the bot's page, with a hollow dot.
A bot that answers people outside asks you about a message that looks like phishing, rather than answering it: one that wants someone to open files, sign in, or pay, with another sign, like a product you don't sell or a deadline. It says Looks like phishing in red in the chat and in Decisions. Don't open its links: close it, or answer the bot if it's real. Links people outside send never open with one tap in a bot's chat: they show as text.
Notifications follow your choices in Settings ▸ Notifications. On your phone, in your browser, and in Chat with Work Desktop they show the bot's name and the start of what it said, or what it asks, unless you turn Show the chat and its answer off. Emails gather what still waits for you into one: the bot's name, what waits, how many, and a link, never what it said. They're off while those notifications reach you, except when a bot pauses itself; otherwise they come as a digest an hour later, leaving out what you've opened or decided. Choose Off, Digest, or Immediately under Email notifications.
Testing a bot
A bot's Tests tab holds its tests, for you and anyone who watches it. Each test says what happens (one of its triggers' events with its fields, a message someone sends it, or its timed run) and what the bot should do then: the changes it should ask for, tools it must never use, changing nothing, telling you or staying quiet, and, for what those can't say, a sentence a model judges, like "the comment is a short recap that asks nothing".
Add tests three ways: Add a test writes one by hand; Turn into a test, beside one of its recent runs, makes one from what started that run and what you approved or denied in it; Change it, at the top of the bot's page, opens its chat, where you describe tests in your words ("add a test where the issue is a duplicate"), and each one it proposes is added only once you approve it. A bot made from a recipe starts with a few.
Run tries the bot on every test, one after another, as a try does: it follows its instructions with its tools, and nothing it asks to change happens. Each test passes or fails with why, and opens the chat it ran in. A run spends the bot's credits, about what the tab says before you press it, and stops if they run out.
When it stops
A trigger pauses itself and tells you if it gets more events than it may run on (at most 20 runs an hour) for three hours in a row, if its runs keep setting it off, if its address gets many requests with a wrong signature, if the connection it listens through stops working, or if the bot it starts after was deleted. Events about a change one of your own chats just made are ignored, so a bot doesn't set itself off. Resume it from its page once that's sorted.
Pausing and deleting
Pause, at the top of a bot's page, stops it from starting until you press Resume. Its triggers and settings stay as they are. The people who watch a shared bot can pause it too.
Delete, beside it, removes the bot for good. You delete a bot of yours; owners and admins delete a shared one. It asks first, then:
- Its triggers go, so nothing starts it again: times stop, its apps' events and addresses stop reaching it, and for a shared bot its ways in from outside (its API keys, Chatwoot, Slack, Discord, GitHub) stop too.
- Whatever it was doing stops. A run that's answering stops at its next step, and changes or questions waiting for a decision are passed on, so nothing it proposed happens later and they leave your Decisions.
- Bots that start after its runs pause, and whoever set those triggers up hears why.
- Its runs stay. A bot of yours ran as you, so its runs are yours, to read and keep asking in. A shared bot's stay in its project for everyone there to read, but nobody can ask in them anymore. Its conversations with people outside are still deleted a year after their last message, as they would have been.
From a terminal
Chat with Work Desktop's cww bots command makes and manages bots from a terminal, as you, for you or an agent. It can't do anything you couldn't do here.
Privacy
A bot of yours runs as you, in your organization, and reads only with the connections given to it. Events are kept encrypted for 30 days once they ran, and for 7 days when they didn't; the runs a bot starts stay until you delete them, like any chat. A shared bot's conversations with people outside are deleted with their chats after 12 months without a message. Mail to a trigger's address is received in Frankfurt and deleted from there once it's read.