For most users, the Getting Started Overview is enough. This page is a deeper reference for how the platform’s data models connect. Model 1: Organization & Projects
The Organization & Projects model defines how your company structures AI agents and manages team access.
Organization
Your Organization is the top-level container representing your company’s botBrains account. Each account has exactly one organization.
| Contains | Description |
|---|
| Projects | Every AI agent you create |
| Billing | Subscription plan, usage tracking, payment methods |
| Team Members | People with access to manage your botBrains account |
| Settings | Default configurations and preferences |
In the botBrains data model, “Organization” and “Account” are often used interchangeably.
Projects
Projects are where the real work happens. Each project is a completely independent AI agent with its own configuration, knowledge base, and deployments.
| Contains | Description |
|---|
| Knowledge Sources | Data providers, snippets, and search tables |
| Behavior Configuration | Profiles that control guidance, tools, and how the AI responds |
| Deployments | Versioned releases of your AI configuration |
| User Pools | Collections of users who interact with this project |
| Integrations | Channels like website widgets, Zendesk, Salesforce, Slack |
| Analytics | Metrics, topics, and insights for this AI agent |
When to Create Multiple Projects
| Reason | Example |
|---|
| Different products or brands | Separate AI for each product line, each with its own knowledge base and voice |
| Different departments | Sales, support, and technical teams with different escalation workflows |
| Development stages | Separate Dev, staging, and production environments |
| Languages or regions | Region-specific deployments with localized knowledge |
| Customer segments | Enterprise customers get a different AI experience than self-service users |
While multiple projects can integrate with a single Zendesk or Salesforce Service Cloud instance, only one active integration from the third-party platform to botBrains exists at a time. You might need to consolidate multiple use cases into one project.
Model 2: Users, Conversations & Messages
This model captures who your customers are, what they ask about, and their complete interaction history.
Users own conversations. Each conversation belongs to exactly one user (1-to-many). This is not a group chat model—conversations are between one customer and your AI.
Users
Users represent the people who interact with your AI agent. Each user has a unique identity and maintains conversation history across all interactions.
| Property | Description |
|---|
| Profile | Name, email, phone number, identification |
| Custom Attributes | Your own data fields for segmentation and personalization |
| Preferences | Language, timezone, and other settings |
| External IDs | Identifiers from your systems (CRM, support platform, database) |
| Conversation History | All conversations this user has ever had |
| Labels | Tags for organization and segmentation |
Conversations
Conversations are individual interaction sessions between a user and your AI agent. Each conversation belongs to exactly one user and contains a sequence of messages.
Conversations track status, ratings, timestamps, channel information, labels, and topic classification. They flow through these states:
| Status | Meaning |
|---|
| Active | Ongoing conversation, user actively participates |
| Resolved | Successfully answered |
| Escalated | Handed off to human agent |
| Abandoned | User stopped responding |
Messages
Messages are the individual exchanges within a conversation. Each message has a role (user, assistant, or operator), text content, optional attachments, and labels. Messages maintain chronological order and are immutable once created.
Message types include standard messages, comments (internal notes from team members, not visible to the user), system-generated notes, and conversation summaries.
Model 3: Channels, Aliases & Deployments
This model defines how you deploy AI versions across platforms. It separates configuration development from production deployment, enabling safe updates and version control.
Channels
Channels are the platforms where users interact with your AI. You can have multiple channels of the same type (for example, multiple website widgets for different sites).
| Channel | Description |
|---|
| Website | Chat widget embedded on your website. Three modes: launcher, inline, iframe. |
| Zendesk | Automates ticket responses, predicts fields, handles ticket workflows. |
| Salesforce Service Cloud | Responds to cases, populates fields, manages case workflows. |
| Slack | DM the bot or mention it in channels. |
| WhatsApp | Messaging platform integration (coming soon). |
Aliases
An alias is a named pointer to a specific deployment version. Think of it as a bookmark—channels connect to “Production,” and you control which version “Production” points to.
| Type | Description |
|---|
| Mutable | You can update to point to different versions. Used for “Production,” “Staging,” etc. |
| Immutable | Once set, always points to the same version. Used for rollback points. |
Deployments (Versions)
Deployments are sequentially numbered, immutable snapshots of your AI’s complete configuration at a specific point in time. Each version contains the profile configuration (guidance, tools, LLM settings), a knowledge snapshot (all sources at build time), and metadata.
Knowledge is versioned. Changes to data providers don’t affect deployed channels until you build a new version. This keeps deployed behavior stable and rollback-safe.
Model 4: Guidance, Actions & Knowledge
These three components live inside Profiles and together define how your AI behaves, what it can do, and what it knows.
Guidance Rules
Guidance rules control how your AI behaves. Each guidance contains natural language instructions, tool permissions (allowed_tools), audience rules for when it applies, and an active/draft state. Multiple guidances evaluate in priority order.
When you reference tools in instructions using backticks (for example, `search_orders`), botBrains automatically detects them and manages the allowed_tools list.
Actions
Actions are tools and capabilities your AI can execute:
| Type | Description |
|---|
| Built-in Tools | Web search, fetch web pages, offer handoff, escalate to human, search knowledge |
| Search Tables | Structured data (CSV, JSON) queryable with filters and ranges |
| MCP Servers | External integrations via Model Context Protocol (Salesforce, Stripe, Shopify, Zapier, or your own APIs) |
| Triggers | Automated rules that fire before the AI responds (block, assign/unassign label) |
Knowledge
Knowledge is your AI’s information foundation—the sources it draws upon for accurate, grounded responses.
| Component | Description |
|---|
| Data Providers | Sources of content: web crawler, Confluence, or manual (snippets) |
| Sources | Individual documents/pages within providers |
| Chunks & Embeddings | Indexed segments with vector representations for semantic search |
