Core concepts

This is the vocabulary used everywhere else in the docs. Skim it once; come back when an unfamiliar term appears.

Identity and multi-tenancy

Tenant — A customer of CraftBot (typically one company). Every tenant has its own isolated data. Cross-tenant data access is impossible by design.

Workspace — Synonym for tenant in user-facing copy. The “workspace” is the area you sign into.

User — A person with a CraftBot login. Belongs to exactly one tenant.

Role — Permission profile attached to a user (agent, supervisor, admin, super_admin, readonly).

Department — A high-level organizational unit (e.g. “Claims”, “Member Services”). Used for routing and reporting.

Team — A sub-grouping of agents inside a department. Conversations can be routed or transferred to a team rather than a specific person.

Conversational entities

Contact — An external person who messages your business. Identified by phone number on WhatsApp.

Conversation — A unit of customer engagement spanning one or more inbound and outbound messages. Has a status (open, pending, resolved, archived) and an assignee (an agent, a team, or the bot).

Message — A single inbound or outbound payload (text, button reply, media). Each message belongs to a conversation.

Sub-state — A finer status indicator inside open (for example waiting on customer, waiting on agent, waiting on system). Used by supervisors to spot stalled chats.

Whisper — An internal note attached to a conversation. Visible to other agents and supervisors, never sent to the customer.

Disposition — A structured close-reason form an agent fills out when resolving a conversation. Disposition forms are admin-defined under Settings → Disposition Forms.

Bot engine

Recipe — A bot conversation flow. Built visually on the canvas. Has draft and published versions, with version history.

Node — A single step in a recipe — Message, Question, Condition, API call, Transfer, Close, and many more. Each node type has its own configuration drawer.

Port — A connection point on a node — in for inputs, next / fallback / branch_* / btn_* etc. for outputs.

Edge — A connection between two ports.

Variable — A named value collected or set during a flow run. Lives for the duration of the bot session and can be referenced inside other nodes’ configuration.

Flow session — One execution of a recipe for a specific contact. Created when a trigger fires and disposed when a Close, Transfer, or terminal node is reached.

Trigger — A rule on a recipe that decides which inbound message starts that recipe (keyword match, channel, fallback, etc.).

AI Agents

AI Agent — An LLM-backed agent a recipe can call. CraftBot supports two kinds. A webhook agent is an external AI service (n8n, LangGraph, or any HTTP-callable platform) that CraftBot calls from the Agent node — AI orchestration lives outside the platform. An in-platform agent is one CraftBot runs itself by calling a language-model provider (Anthropic or OpenAI) directly, answering from a knowledge base; it is called from the AI Agent node.

Agent registry — The admin-configured catalogue of both kinds of agent, edited under Settings → AI Agents.

Safety pre-filter — A keyword filter that runs before every Agent and AI Agent node call. Configured under Settings → Safety. Cannot be bypassed when the workspace has safety enforcement on.

Smart Plugs, Custom Entities, and Connectors

Connector — A reusable definition of how to talk to an external system (Freshdesk, Zoho, HubSpot, Salesforce, Generic REST, or a custom in-house system you author). Lives under Settings → Connectors.

Smart Plug — An admin-configured action card that lives in the agent right rail. Each plug exposes one or more buttons (e.g. Create Ticket, Escalate, Resolve) that fire HTTP calls against a connector. Some plugs fire automatically when a conversation opens; others wait for the agent to click. Configured under Settings → Smart Plugs.

Custom Entity — A workspace-defined data type attached to contacts (Salesforce/HubSpot-style “custom object”) — for example Policy, Claim, or Ticket. Rendered in the agent right rail as a table or detail view. Configured under Settings → Custom Entities.

Field source mode — Every custom-entity field is either integration (populated only by Smart Plug responses, read-only for agents) or manual (agent input only, never overwritten by a plug). The two are mutually exclusive by design.

Channels

Channel — A communication surface (WhatsApp, email, web widget, etc.). Today CraftBot ships with WhatsApp Cloud API direct integration; email outbound and other channels expand over time.

Channel config — A specific WhatsApp number provisioned in the Settings UI. Includes Phone Number ID, WABA ID, app credentials. Multiple numbers per workspace are supported.

Webhook verify token — A shared secret between Meta and CraftBot used to verify the webhook subscription endpoint at setup time.

Email server — An outbound email adapter (Generic SMTP, Microsoft 365 OAuth2, or Gmail OAuth2) configured under Settings → Email Servers. Used for invitations, password resets, and notification emails.

Operational

Assignment — The act of giving a conversation to an agent. May be automatic (round-robin, least-busy) or manual (supervisor reassigns).

Business hours — Workspace-level schedule that recipes can branch on (via the Business Hours node) and that affects auto-assignment fallback. Configured under Settings → Business Hours.

SLA rule — A first-response or resolution-time target attached to a queue. Breaches surface on the dashboard and can fire notifications.

Nudge rule — Time-based prompt that fires reminders to agents (or supervisors) when a conversation has been stalled for too long.

Tag — A free-form label attached to a conversation or contact. Tags are used for filtering, routing, and reporting.

Knowledge base (KB) — A curated set of question-answer pairs queried by the FAQ node in recipes. Authored under Settings → Knowledge Bases.

CSAT — Customer satisfaction survey, sent automatically on close or via a CSAT node mid-flow. Configured under Settings → Close CSAT.

Campaign — An outbound broadcast sent to a defined audience via an approved WhatsApp template. Managed under Campaigns.