Skip to main content
A goal bot is three things:
  1. A prompt — the whole job, in plain English
  2. Tools — exactly what it is allowed to do
  3. Tags — which leads it answers
When a lead carrying one of its tags replies, the bot reads the conversation, decides what to say, calls whatever tools it needs, and answers. One bot runs the whole conversation: it qualifies and books. There is no handoff to a second bot.
Goal bots used to be built from stages — step 1, step 2, step 3, each with its own advance conditions. Stages are gone. The conversation itself is the state: the bot reads the thread and knows what it has already asked, so there is no step pointer to get stuck or jump ahead.

​
Writing the prompt

Write it the way you would brief a new rep. Ordered instructions are fine — the bot follows them without needing a stage machine.
Things worth putting in the prompt: answer a direct question before carrying on, reply in the language the lead is writing in, and drop a question after asking it twice rather than looping.

​
Tools

A bot can only use what you give it, so it can never talk about doing something it cannot do. Only one calendar’s booking tools are ever handed to a bot, so it cannot book into the wrong calendar when both are connected.
get_lead_details is how the bot picks up context your team already has. Whatever is in a lead’s Notes — “quoted in March, went quiet”, “only answers after 5pm” — comes back with it, so the bot works from it instead of asking the lead something you already know. Notes are treated as internal: the bot uses them for context and does not read them back to the lead.

​
Tags decide who it talks to

includeTags is the trigger. The bot answers a lead carrying any one of them. excludeTags is the veto — it never answers a lead carrying one of those.
Tags are matched exactly and are case sensitive. A bot pointed at a tag your CRM workflow never actually applies will never fire for anyone, and it fails silently — the lead replies and nothing happens. Check the tag exists on real leads in your CRM, not just in the bot.An empty includeTags means every lead who replies. The oldest active bot with no tag filter answers every conversation before any other bot sees it.
A common pattern is to tag on completion: onDoneTag is applied to the lead once the bot books, which your CRM workflow can pick up.

​
Reply hours — when it is allowed to answer

Each bot has its own hours: pick the days it answers, and a start and end time for each. Outside them the bot sends nothing and a person answers instead. You set it on the bot’s own page, under Reply time settings. A bot with no hours answers at all times. That is how every bot starts, so setting hours is the only thing that can make a bot quieter.

​
What happens outside the hours

The bot sends nothing and drafts nothing — but you still get told. The ordinary new-reply email and Telegram arrive, exactly as they would for a workspace with no bot at all. No empty draft, no “AI needs help” alert. Only the bot’s work stops.
Nothing is queued. A message that arrives outside the hours is not answered later when the window reopens. There is no catch-up. From that point the conversation is yours to answer by hand.

​
The override

One switch, three positions: An override does not erase your schedule. Clear it and your saved days come back. It has no expiry — one set on a Friday is still set on Monday.

​
Night shifts

Set an end time earlier than the start and the window runs past midnight. 20:00 to 08:00 on Monday means Monday evening through Tuesday 08:00 — the hours belong to the day the shift starts. For a bot that answers all night, every night, set the shift on each day it begins: Monday to Friday at 20:00–08:00 answers from Monday night through Saturday morning, and stays quiet in the daytime gap between shifts.

​
Worth knowing

  • The times use your workspace timezone, not the lead’s and not ours. Daylight saving is handled, so 09:00 stays 09:00 across a clock change.
  • The end time is exclusive: 09:00–17:00 answers at 16:59 and not at 17:00.
  • There is no workspace-wide schedule. Hours are per bot, so your booking bot can run late while an outreach bot stops at five.
Hours apply to the bot that answers, which is not always the one you set them on. Routing happens first. A bot with an empty includeTags answers every lead before the default Auto Replies bot does — so hours on the default bot do nothing if you also have an untagged bot. Check which bot actually answers a lead before you schedule it.
You can also read and set this over the API — see Reply Hours.

​
Two things the engine enforces on its own

These hold no matter what the prompt says. It cannot book a time the lead was never offered. A booking is refused unless an earlier bot message actually named a clock time. A “yes” to the trial is not a “yes” to a time — the bot has to offer, and the lead has to pick. It cannot book a time the calendar did not return. The requested slot is re-checked against live availability before booking; on a miss the bot is handed the real nearest times so it re-offers instead of inventing one.

​
Saving what the bot learns

A bot can write the answers it gets straight onto the lead. List what you want under collectFields:
Nothing goes in the prompt and there is no tool to call. After each reply the bot reads the conversation and saves whatever it now knows onto the lead’s customFields, in the lead’s own words:
They show on the lead page and in the inbox, next to the fields your CRM imported. Nothing new to set up. A field they have not answered yet is left empty rather than guessed, and fills in later as the conversation goes on. An earlier answer is never overwritten with a blank. Leave collectFields out and nothing is extracted.

​
Typing indicator

Bots show the typing indicator before replying, because a tool loop makes real calls and checking a calendar can take a few seconds. Turn it off for a particular bot with "typingIndicator": false. It only works on lines where the Private API is available. Everywhere else it is skipped regardless of the setting.

​
Testing before you go live

Create the bot with "status": "paused", then use Simulate to run it against a transcript. Nothing is sent — no message, no draft, no notification — and the response shows which tools actually ran, so a bot that only talks about checking a calendar is obvious straight away. When it reads right, PATCH it to active.
A goal bot outranks the knowledge-base reply bot. When one matches a lead, it owns the reply and the KB bot is skipped, including when the KB bot is in manual mode.

​
API

Goal bots are fully manageable with a workspace API key — prompt, tools, tags, tone, and status. See List Goal Bots to get started. /api/goal-bots and /api/tasks are the same API. /api/tasks is the name from before the engines merged and still works; responses carry both goalBots and taskAgents keys.