The four models that make up the botBrains platform
For most users, the Getting Started Overview is enough. This page is a deeper reference for how the platform’s data models connect.
botBrains organizes your AI operations around four models: Organization & Projects for structure, Users, Conversations & Messages for customer interactions, Channels, Aliases & Deployments for versioned releases, and guidances, actions & knowledge for AI behavior.
People with access to manage your botBrains account
Settings
Default configurations and preferences
All projects roll up to organization-level billing. Team members can receive access to multiple projects, and admins can access all projects within the organization.
In the botBrains data model, “Organization” and “Account” are often used interchangeably.
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
Projects are fully isolated—they don’t share knowledge or configurations by default. Each has its own API keys, permissions, and analytics.
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.
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 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
You can identify users by email, phone number, or external ID. The platform tracks anonymous users by device/session until they identify themselves.Users belong to a User Pool scoped to your organization. You can share user pools across projects if needed.
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:
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.
This model defines how you deploy AI versions across platforms. It separates configuration development from production deployment, enabling safe updates and version control.
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.
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.
When you update an alias, all connected channels switch immediately with no downtime.
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.
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.
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
Knowledge supports audience filtering per source—for example, enterprise-only documentation. Every AI response tracks which sources informed it, and users can view source attributions.When you build a deployment, the system captures all three components (guidances, actions, knowledge) into an immutable version. Changes to any of them require a new build and deploy.
