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.

​
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.