Bots and automations

Bots are AI teammates in your space. Automations are rules: when this happens, if these checks pass, do these steps. You make both by asking the AI ("add a helper bot people can @mention", "every Monday at 9, post the week's open tasks in General"), by hand, or from your own AI over MCP. Every change is a proposal you approve and can undo.

For people #

• Add the Bots kit (HQ → Library) for the Bots page: what's waiting for you, your bots and automations with an on/off switch, and what happened. Recipes: Helper bot, Welcome message, Reply drafts, Daily digest, Coins for posts.
• Bots ask first. Until you set a bot to act on its own, everything it would change (a post, a record, a notification, coins, any other action) waits on the Bots page. You can change the words before you approve. In a kids space bots always ask a grown-up.
• A bot's role decides what it may do, like a person's: where it may post, whether it may add or change records. Bots never approve anything.
• Reply drafts: on a help desk, a bot drafts the answer and your teammate sends it as themselves.
• @mention a bot by name in a chat to ask it something. Its answer counts against your daily AI use; automations count against the space's.
• Webhooks: let an outside service (a form tool, a shop, a script) start an automation. Make the address on the page with a bots.hooks block; it's shown once.

For builders #

Blueprint entries (full rules in convex/kits/bots/model.ts, the AI's guide part bots):

{
  "bots": [{ "id": "helper", "name": "Helper", "role": "bot", "instructions": "Answer briefly.",
             "tools": ["read_conversation", "post_message", "list_records"], "approval": "ask" }],
  "automations": [{ "id": "helper-answers", "name": "Helper answers mentions",
    "when": { "event": "post", "mentions": "helper" },
    "do": [{ "do": "ask", "bot": "helper", "prompt": "{{person.name}} asked: {{text}}" },
           { "do": "post", "reply": true, "text": "{{last}}", "as": "helper" }] }]
}

• Bot fields: id, name, about, icon, role, instructions, tools, approval ("ask"|"auto"), askFor, approvers, model ("small"|"large"), perDay, on. builder is the AI chat: set its name, instructions and model only.
• Tools: any tool from the one tool list (the same ones MCP clients and the AI chat use), except approving. A tool runs as the bot's account, so its role applies. Tools that change something follow the approval rules; proposals always wait.
• Triggers (when.event): record, record.changed, post, join, booking, play, review, any event a kit reports, plus schedule (every 15m, 30m, hour, day, week, month; at, day, timezone), webhook and manual. Other keys filter on the event's fields (collection, feed, board…); stream also matches every case in a queue; mentions names a bot; fromBots hears bots too.
• Checks (if): [{ path, is | not | contains | gt | lt | exists }].
• Steps (do): post, add_record, update_record, notify, give (coins and other Ledger units; never money), ask (a bot thinks; its answer is {{last}}), wait, call (a connection), tool (any tool, as a bot). Text is a template: {{text}}, {{person.name}}, {{data.x}}, {{last}}, {{date}}, {{space.name}}.
• Approval: words you wrote into an automation go as written; words a bot wrote follow its approval; as: "approver" makes a draft the approver sends; approval: "ask" on an automation makes every step wait.
• Safety: an automation never starts itself again, chains stop after 3 rounds, per-day caps on every bot (default 50) and automation (default 200), webhooks 60 a minute and 16 KB.

Blocks: bots.list, bots.waiting, bots.runs, bots.run, bots.ask, bots.hooks.

MCP tools: read_conversation, post_message, notify, give, run_automation, ask_bot, list_runs, list_waiting, decide_action (plus propose_change for making bots and automations).

Webhook: POST {CONVEX_SITE_URL}/hooks/<secret> with a JSON body; answers 202, 404, 409, 413 or 429.