Skip to main content
For most users, we recommend only reading the Getting Started Overview first to get a high-level understanding of the platform. This is a more lengthly explainer.

​
Why These Models Matter

The four data models work together to support your complete AI customer service workflow:

Organization & Projects

Manage your company’ AI agents, team access, and billing.

Users, Conversations & Messages

Track customer identities and their interactions with your AI.

Channels, Deployments & Aliases

Deploy you AI agents across platforms and integrations in a versioned manner.

Guidances, Actions & Knowledge

Define how your AI behaves and what it knows to assist customers effectively.

​
Model 1: Organization & Projects

The Organization & Projects model defines how your company structure AI agents and manages team access.

​
Overview

Organization (Your Company)
├── Project A (Support Bot)
├── Project B (Sales Assistant)
└── Project C (Internal IT Help)
Organization - The top-level container representing your company or business entity Projects - Independen AI agents, each with its own configuration, knowledge, and deployments

​
Visual Diagram

​
Organization: The Top-Level Container

Your Organization represents your company’s botBrains account. It’s the highest level in the hierarchy and handles company-wide concerns.

​
What It Contains

All Projects - Ever AI agent you create Billing Information - Subscription plan, usage tracking, payment methods Team Members - People with access to manage your botBrains account Organization Settings - Default configurations and preferences

​
Key Characteristics

Single Organization Per Account - Each botBrains account has exactly one organization Centralized Billing - All projects roll up to organization-level billing Shared Resources - Team members can be granted access to multiple projects Organization-Level Roles - Admins can access all projects within the organization

​
When You Interact With It

You work at the organization level when:
  • Setting up billing and subscriptions
  • Managing team members and permissions
  • Viewing aggregate usage across all projects
  • Configuring organization-wide settings
In the botBrains data model, “Organization” and “Account” are often used interchangeably. An account represents your company’s presence in botBrains.

​
Projects: Independen AI agents

Projects are where the real work happens. Each project is a completely independen AI agent with its own configuration, knowledge base, and deployments.

​
What a Project Contains

Knowledge Sources - Data providers, snippets, and search tables specific to this AI 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 specifi AI agent

​
Key Characteristics

Complete Isolation - Projects don’t share knowledge or configurations by default Independent Deployments - Each project can be deployed to different channels Project-Scoped Permissions - Team members can have access to specific projects only Unique API Keys - Each project has its own authentication credentials Separate Analytics - Metrics and insights are tracked per project

​
When to Create Multiple Projects

Create separate projects for: Different Products or Brands Separate AI for each product line or brand identity. Each gets its own knowledge base and can have a distinct voice and behavior. Different Departments Sales, support, and technical teams often need different knowledge and different escalation workflows. Separate projects keep these concerns isolated. Development Stages Maintain separate development, staging, and production environments. Test changes in development before deploying to customers. Different Languages or Regions Region-specific deployments with localized knowledge and language support. Allows customization for different markets. Customer Segments Enterprise customers might need a different AI experience than self-service users. Separate projects enable distinct treatment.
While there could be mulitple projects having integrations with a single Zendesk or Salesforce Service Cloud instance, there may only be one active integration from the 3rd party platform to botBrains at a time. So you might need to map multiple people into one project.

​
How They Relate: Organization Owns Projects

Organization: Acme Corp
│
├─ Billing
│   ├─ Plan: Enterprise
│   ├─ Usage: All projects combined
│   └─ Payment method: Credit card
│
├─ Team Members
│   ├─ Alice (Admin) - Access to all projects
│   ├─ Bob (Support Lead) - Access to Support project only
│   └─ Carol (Sales Manager) - Access to Sales project only
│
└─ Projects
    ├─ Project 1: Customer Support
    │   ├─ Knowledge: Product docs, FAQs, policies
    │   ├─ Behavior: Support-focused guidance
    │   ├─ Deployments: Website widget, Zendesk
    │   └─ User pool: Customers
    │
    ├─ Project 2: Sales Assistant
    │   ├─ Knowledge: Pricing, features, case studies
    │   ├─ Behavior: Sales-focused guidance
    │   ├─ Deployments: Website widget, Salesforce
    │   └─ User pool: Prospects
    │
    └─ Project 3: Internal IT Helpdesk
        ├─ Knowledge: IT policies, troubleshooting
        ├─ Behavior: Internal-focused guidance
        ├─ Deployments: Slack
        └─ User pool: Employees

​
Why This Structure Matters

Billing Simplicity All projects under one organization share a single subscription. You don’t need separate accounts or payment methods for different AI agents. Team Management Grant organization-level access to admins who need to see everything, or project-level access to specialists who only need specifi AI agents. Clean Separation Projects are completely independent. Changes to on AI agent never affect another, preventing accidental cross-contamination of knowledge or settings. Easy Scaling Start with one project and add more as your needs grow. No need to restructure or migrate - just create new projects when you need them.

​
Practical Example: E-Commerce Company

Organization: Acme Retail Inc Team Members:
  • Sarah (CEO) - Organization Admin
  • Mike (Support Director) - Access to Customer Support project
  • Jennifer (Sales VP) - Access to Sales project
  • David (IT Manager) - Access to IT Helpdesk project
Projects: Project 1: Customer Support Bot
  • Purpose: Answer order questions, shipping inquiries, returns
  • Knowledge: Product catalog, shipping policies, return procedures, FAQs
  • Deployments: Website widget (launcher mode), Zendesk integration
  • User Pool: Customers who placed orders
  • Analytics: Track CSAT, resolution rate, common topics
Project 2: Pre-Sales Assistant
  • Purpose: Help potential customers understand products and pricing
  • Knowledge: Product features, pricing, comparisons, case studies
  • Deployments: Website widget (different pages), Salesforce integration
  • User Pool: Website visitors, potential customers
  • Analytics: Track conversion influence, common questions
Project 3: Internal IT Helpdesk
  • Purpose: Help employees with IT issues and questions
  • Knowledge: IT policies, software guides, troubleshooting docs
  • Deployments: Slack bot
  • User Pool: Employees
  • Analytics: Track most common IT issues, time saved
Billing:
  • All three projects covered under single Enterprise plan
  • Usage tracked separately per project but billed together
  • One invoice, one payment method

​
Best Practices

Start Simple Begin with one project to validate you AI agent works well. Add more projects as your needs grow and you understand the platform better. Use Descriptive Names Name projects clearly: “Customer Support Bot”, “Sales Assistant”, “IT Helpdesk”. Avoid generic names like “Project 1” or “Bot A”. Plan for Isolation Don’t try to share knowledge across projects directly. If multiple projects need the same information, use data providers to sync from a single source. Organize by Function Group projects by their purpose (support, sales, internal) rather than by channel or deployment method. Manage Access Carefully Give team members access only to the projects they need. This prevents accidental changes and keeps analytics focused.

​
Model 2: User, Conversation, Messages

The User model defines how customers and their conversations are tracked and organized. This model captures who your customers are, what they’re asking about, and the complete history of their interactions.

​
Overview

User (Customer)
└── Conversation 1
    ├── Message 1 (User question)
    ├── Message 2 (AI response)
    ├── Message 3 (User follow-up)
    └── Message 4 (AI response)
└── Conversation 2
    ├── Message 1 (User question)
    └── Message 2 (AI response)
User - A person who interacts with you AI agent Conversation - A session of interaction between a user and your AI Messages - Individual exchanges within a conversation

​
Visual Diagram

​
Critical Design Note: User Owns Conversation

Important: In botBrains, the User model is NOT on the Messages like in typical group chat systems.Instead, exactly ONE user owns each conversation. This is a 1-to-many relationship: each user can have multiple conversations, but each conversation belongs to exactly one user.
This design reflects reality in customer service: conversations are between one customer and your AI. It’s not a group chat where multiple people participate in the same conversation.

​
Users: Customer Identity

Users represent the people who interact with you AI agent. Each user has a unique identity and maintains conversation history across all their interactions.

​
What a User Contains

User Profile - Name, email, phone number, and 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

​
User Properties

Standard user fields include: 
{
  "id": "usr_abc123",
  "first_name": "Sarah",
  "last_name": "Chen",
  "email": "sarah.chen@example.com",
  "email_signed": true,
  "phone": "+14155551234",
  "phone_signed": false,
  "external_id": "cust_789xyz",
  "timezone": "America/Los_Angeles",
  "locales": ["en-US", "zh-CN"],
  "last_seen_at": "2025-11-29T18:45:00Z",
  "external_attributes": {
    "subscription_tier": "enterprise",
    "account_status": "active",
    "signup_date": "2023-06-15",
    "lifetime_value": 24500
  }
}

​
User Identification Methods

Email Address - Primary identifier, tracks verification status Phone Number - Mobile or phone numbers, especially for messaging integrations External ID - Your unique identifier from CRM, authentication, or database Anonymous Users - Users who haven’t provided information are tracked by device/session

​
Key Characteristics

User Pools Scope Users - Users belong to a user pool, which belongs to a project’s organization Persistent Identity - Users maintain history across multiple conversations and channels Cross-Project Potential - User pools can be shared across projects if needed Secure Identification - Support for signed user data to prevent impersonation

​
Conversations: Interaction Sessions

Conversations are individual interaction sessions between a user and you AI agent. Each conversation belongs to exactly one user and contains a sequence of messages.

​
What a Conversation Contains

Messages - The sequence of user questions and AI responses Metadata - Status, ratings, timestamps, channel information Context - Information about where the conversation happened Labels - Tags for organization and classification Analytics - Topic classification, sentiment, resolution status

​
Conversation Properties

Important conversation fields include: 
{
  "id": "conv_xyz789",
  "user_id": "usr_abc123",
  "alias_id": "prod_website",
  "created_at": "2025-12-01T10:30:00Z",
  "first_message_time": "2025-12-01T10:30:15Z",
  "last_message_time": "2025-12-01T10:35:42Z",
  "conversation_length": 8,
  "status": "resolved",
  "rating_score": 5,
  "rating_comment": "Very helpful, thanks!",
  "labels": ["billing", "subscription-change"]
}

​
Key Characteristics

User-Scoped - Each conversation belongs to exactly one user (1-to-many relationship) Time-Bound Sessions - Conversations capture a logical interaction period Rich Context - Includes channel, deployment, and environmental information Trackable Outcomes - Status, ratings, and resolution metrics

​
Conversation Status Lifecycle

Conversations typically flow through these states: Active - Ongoing conversation, user is engaged Resolved - Successfully answered, user satisfied Escalated - Handed off to human agent for complex issues Abandoned - User stopped responding, conversation inactive

​
Messages: Individual Exchanges

Messages are the individual exchanges within a conversation - each question from the user and each response from your AI.

​
What a Message Contains

Message Text - The actual content of the message Role - Whether the message is from the user or assistant Metadata - Timestamps, language, source information Attachments - Files, images, or audio shared in the message Labels - Topic tags and classifications Translations - Messages in different languages

​
Message Properties

Standard message fields include: 
{
  "id": "msg_123abc",
  "conversation_id": "conv_xyz789",
  "project_id": 42,
  "role": "user",
  "text": "How do I upgrade my subscription?",
  "sender": "Sarah Chen",
  "created_at": "2025-12-01T10:30:15Z",
  "parent_id": null,
  "files": [],
  "labels": ["billing", "subscription"],
  "text_translation": null
}

​
Key Characteristics

Conversation-Scoped - Messages belong to a single conversation Ordered Sequence - Messages maintain chronological order Parent Linking - Each message links to previous message for context Immutable - Once created, messages typically aren’t edited Rich Content - Support for text, files, and multimedia

​
Message Types

Standard Message - Normal user question or AI response Comment - Internal note from team members (not visible to user) Note - System-generated annotation Summary - Condensed conversation recap

​
How They Relate: The Complete Flow

User Pool: Acme Customers
│
├── User: john@example.com
│   ├── Profile
│   │   ├── Name: John Smith
│   │   ├── External ID: cust_123
│   │   ├── Attributes: {plan: "enterprise", region: "us-west"}
│   │   └── Labels: ["vip-customer"]
│   │
│   ├── Conversation #1 (Dec 1, 10:30 AM)
│   │   ├── Status: Resolved
│   │   ├── Channel: Website Widget
│   │   ├── Rating: 5 stars
│   │   ├── Labels: ["billing", "payment"]
│   │   └── Messages:
│   │       ├── Message 1: "How do I update my payment method?" (user)
│   │       ├── Message 2: "I can help you update..." (assistant)
│   │       ├── Message 3: "Perfect, thanks!" (user)
│   │       └── Message 4: "You're welcome! Is there..." (assistant)
│   │
│   ├── Conversation #2 (Dec 2, 2:15 PM)
│   │   ├── Status: Escalated
│   │   ├── Channel: Zendesk
│   │   ├── Labels: ["technical-issue", "api"]
│   │   └── Messages:
│   │       ├── Message 1: "Getting 401 errors on API calls" (user)
│   │       ├── Message 2: "Let me help troubleshoot..." (assistant)
│   │       ├── Message 3: "Still not working" (user)
│   │       └── Message 4: "I'll escalate to our team..." (assistant)
│   │
│   └── Conversation #3 (Dec 5, 9:00 AM)
│       ├── Status: Active
│       ├── Channel: Website Widget
│       └── Messages:
│           └── Message 1: "What's new in v2.0?" (user)
│
└── User: sarah@business.com
    ├── Profile
    │   ├── Name: Sarah Johnson
    │   ├── External ID: cust_456
    │   ├── Attributes: {plan: "starter", region: "eu"}
    │   └── Labels: ["new-customer"]
    │
    └── Conversation #4 (Dec 3, 11:20 AM)
        ├── Status: Resolved
        ├── Channel: Website Widget
        ├── Rating: 4 stars
        └── Messages:
            ├── Message 1: "Do you support GDPR compliance?" (user)
            └── Message 2: "Yes, we are fully GDPR compliant..." (assistant)

​
Why This Structure Matters

Complete Customer Context Every conversation is tied to a user, so you can see the complete support history for each customer. This enables personalized responses and better support over time. Persistent Identity Users maintain their identity across channels and time. Someone who chats on your website today and submits a Zendesk ticket tomorrow is recognized as the same person. Rich Analytics Track metrics by user segment, conversation outcome, and message content. Understand which customers need the most help and what topics drive inquiries. Personalization Opportunities Use user attributes and conversation history to customize AI responses. Enterprise customers can get different guidance than free tier users.

​
Practical Example: SaaS Support

User: alex@startup.com Profile:
  • Name: Alex Martinez
  • External ID: cust_789 (from your database)
  • Subscription: Pro plan
  • Signup Date: 2024-08-15
  • Language: Spanish (es-ES)
  • Labels: [“power-user”, “early-adopter”]
Conversation History: Conversation 1 (Nov 15)
  • Channel: Website widget
  • Topic: Integration question
  • Status: Resolved
  • Rating: 5 stars
  • Messages: 6 back-and-forth exchanges
Conversation 2 (Nov 28)
  • Channel: Zendesk ticket
  • Topic: Billing inquiry
  • Status: Resolved
  • Rating: 4 stars
  • Messages: 4 exchanges
Conversation 3 (Dec 1 - Today)
  • Channel: Slack
  • Topic: Feature request
  • Status: Active
  • Messages: 3 so far, ongoing
Why This Helps:
  • AI recognizes Alex as returning customer
  • Can reference previous conversations
  • Knows to respond in Spanish
  • Understands Alex is a power user on Pro plan
  • Can provide context-aware, personalized support

​
Best Practices

Identify Users When Possible Anonymous users are fine initially, but identification (email, phone, external ID) enables better support and analytics. Use your SDK to identify authenticated users. Use External Attributes Pass custom data from your systems to enrich user profiles. Include subscription tier, account status, or any data useful for personalization. Label Strategically Create labels that match your business processes: “vip-customer”, “churned-user”, “needs-followup”. Use labels to filter and segment users. Monitor Conversation Outcomes Track resolution rates, escalation patterns, and ratings to understand how well your AI serves different user segments. Maintain Data Quality Regularly review and clean user data. Merge duplicate profiles, correct invalid information, and update attributes as customers change.

​
Model 3: Channel, Alias, Deployment (Version)

The Channel model defines how you deploy AI versions across different platforms and integrations. This model separates configuration development from production deployment, enabling safe updates and version control.

​
Overview

Channel (Website)
└── Alias (Production)
    └── Deployment Version #5
        ├── Profile v0.5 (Guidance, Tools, Settings)
        └── Knowledge Snapshot (Data at build time)
Channel - Where users interact with your AI (Website, Zendesk, Salesforce, Slack, WhatsApp) Alias - A pointer to a specific deployment version (“Production”, “Staging”, etc.) Deployment (Version) - An immutable snapshot of your AI configuration and knowledge

​
Visual Diagram

​
Channels: User Interaction Points

Channels are the platforms where users interact with your AI. botBrains supports multiple channel types, each suited to different use cases.

​
Available Channels

Website (Browser) Embed AI directly on your website using chat widgets. Three modes: launcher (chat bubble), inline (embedded in page), iframe (full screen). Zendesk Automate ticket responses in Zendesk. AI drafts or posts responses, predicts fields, and handles ticket workflows. Salesforce Service Cloud Integrate with Salesforce cases. AI responds to cases, populates fields, and manages case workflows. Slack Bring AI assistance into team communication. Users can DM the bot or mention it in channels. WhatsApp Reach customers on their preferred messaging platform (coming soon).

​
Key Characteristics

Platform-Specific - Each channel type has unique configuration options
Connected to Aliases - Channels connect to an alias, not directly to a version
Multiple Instances - You can have multiple channels of the same type (e.g., multiple website widgets)
Independent Configuration - Each channel instance has its own settings (appearance, behavior, etc.)

​
Channel Examples

Your Project: Customer Support
│
├── Channel: Website Widget (Main Site)
│   ├── Type: Browser (Launcher mode)
│   ├── Connected to: Production Alias
│   └── Configuration: Blue theme, bottom-right position
│
├── Channel: Website Widget (Help Center)
│   ├── Type: Browser (Inline mode)
│   ├── Connected to: Production Alias
│   └── Configuration: Embedded in help center page
│
├── Channel: Zendesk Integration
│   ├── Type: Zendesk
│   ├── Connected to: Production Alias
│   └── Configuration: Public mode, auto-respond enabled
│
└── Channel: Internal Slack Bot
    ├── Type: Slack
    ├── Connected to: Staging Alias
    └── Configuration: DM and channel mentions enabled

​
Aliases: Version Pointers

Aliases are named pointers to specific deployment versions. They provide a stable reference point that channels can connect to, while allowing you to change which version is actually running.

​
What an Alias Does

Think of an alias like a bookmark or shortcut:
  • Channels connect to the alias (e.g., “Production”)
  • The alias points to a specific version (e.g., Version #5)
  • You can change which version the alias points to
  • All channels using that alias automatically use the new version

​
Alias Types

IMMUTABLE Aliases Once set, immutable aliases always point to the same version. Used for specific version references or rollback points. MUTABLE Aliases Can be updated to point to different versions. Most common type, used for “Production”, “Staging”, etc.

​
Common Alias Patterns

Production Alias Points to the currently active version that customers interact with. All production channels connect here. Staging Alias Points to a test version for internal validation before going live. Testing channels connect here. Rollback Aliases Immutable aliases pointing to previous good versions, enabling quick rollback if needed.

​
Key Characteristics

Named References - Aliases have descriptive names like “Production”, “Staging” Version Pointers - Each alias points to exactly one deployment version Channel Connections - Channels connect to aliases, not directly to versions Update Propagation - Changing alias target updates all connected channels immediately

​
Deployments (Versions): Configuration Snapshots

Deployments, also called Versions, are numbered, immutable snapshots of your AI’s complete configuration at a specific point in time.

​
What a Deployment Contains

Profile Configuration
  • Guidance instructions
  • Tool configurations
  • LLM settings
  • Audience rules
  • Escalation criteria
Knowledge Snapshot
  • All data provider content at build time
  • Snippet collections
  • Search table references
  • Embeddings index
Metadata
  • Version number (#1, #2, #3…)
  • Profile name (v0.0, v0.1, v0.2…)
  • Creation timestamp
  • Build description

​
Key Characteristics

Immutable - Once created, versions never change Numbered Sequentially - Automatically assigned numbers (#1, #2, #3…) Complete Snapshots - Include both configuration and knowledge at build time Versioned Knowledge - Changes to guidance or knowledge require a redeploy Rollback Ready - Previous versions remain available for rollback

​
The Build Process

Creating a new deployment:
  1. Make Changes - Edit guidance, add knowledge sources, configure tools
  2. Build Version - Navigate to Behavior → Review → Build Version
  3. Capture Snapshot - System captures current profile and knowledge state
  4. Create Deployment - New version created with incremented number
  5. Update Alias - (Optional) Set as active to point Production alias to new version
  6. Deploy to Channels - All channels using the alias switch to new version
Build Time: 30-60 seconds for most configurations
Building creates an immutable deployment. Once built, versions cannot be modified - you must build a new version for any changes.

​
How They Relate: The Complete Architecture

Configuration & Knowledge (Editing)
├─ Guidance Instructions
├─ Data Providers & Snippets
├─ Tool Configuration
└─ Audience Rules

↓ Build Version ↓

Deployment Version #5 (Immutable Snapshot)
├─ Profile v0.5
│   ├─ Guidance: "Be helpful and concise..."
│   ├─ Tools: search_knowledge, search_web
│   └─ Settings: GPT-4, temperature 0.7
└─ Knowledge Snapshot (Dec 1, 2025 10:00 AM)
    ├─ Help docs (120 articles)
    ├─ Product catalog (450 items)
    └─ FAQ snippets (85 entries)

↑ Points To ↑

Production Alias
└─ Description: "Live customer-facing version"

↑ Connected To ↑

Channels (All Use Production Alias)
├─ Website Widget → Production → Version #5
├─ Zendesk → Production → Version #5
├─ Salesforce → Production → Version #5
└─ Slack → Production → Version #5

---

Available Versions (History)
├─ Version #5 (Active) ← Production points here
├─ Version #4 (Dec 1, 9:00 AM)
├─ Version #3 (Nov 28, 3:00 PM)
├─ Version #2 (Nov 25, 11:00 AM)
└─ Version #1 (Nov 20, 2:00 PM)

​
Why This Structure Matters

Safe Updates Build and test new versions without affecting live channels. Only when you’re confident, update the Production alias to point to the new version. Version Control Every change creates a new numbered version. You have a complete audit trail of what changed and when. Easy Rollback If a deployment causes issues, simply point the Production alias back to a previous version. All channels switch back immediately. Consistent Deployment All channels connected to the same alias use the same version. Update once, deploy everywhere. Knowledge Versioning Knowledge is captured at build time. Changes to data providers don’t affect deployed versions until you rebuild and redeploy.

​
Versioning and Knowledge Updates

Critical Concept: Knowledge is versioned along with your configuration.When you update a data provider or add snippets, those changes are NOT immediately available to deployed channels. You must build a new version to incorporate knowledge updates.
The Knowledge Snapshot Process:
  1. Data Provider Syncs - Your documentation, FAQs, etc. are synced from sources
  2. Knowledge Updated - New content is available in the knowledge base
  3. Staleness Indicator - Platform shows “Knowledge updated, rebuild needed”
  4. Build New Version - Creating a new version captures current knowledge state
  5. Deploy - Set new version as active for channels to use updated knowledge
Why This Matters:
  • Deployed versions are stable - knowledge doesn’t change mid-conversation
  • You control when knowledge updates go live
  • You can test knowledge changes before deploying to customers
  • Rollback includes both configuration AND knowledge state
For frequently updating knowledge sources, schedule regular builds (weekly or monthly) to keep your AI current. This ensures customers always have access to latest documentation and information.
Learn more: See Versioning Guide for detailed information on managing versions and deployments.

​
Best Practices

Use Meaningful Alias Names Name aliases clearly: “Production”, “Staging”, “Testing”. Avoid generic names like “Alias 1”. Build Versions Strategically During active development, build often to test changes. For stable deployments, build less frequently - batch multiple small changes into one version. Test Before Production Use a Staging alias to test new versions before updating Production. Catch issues before customers see them. Monitor After Deployment Watch conversations closely for 24-48 hours after deploying a new version. Check metrics, read conversations, verify everything works as expected. Keep Version History Don’t delete old versions. They serve as rollback points and provide an audit trail of changes. Document Changes Keep notes on what changed in each version. This helps track improvements and troubleshoot issues. Regular Knowledge Rebuilds If you have frequently updating data providers, schedule regular builds (weekly/monthly) to incorporate latest knowledge.

​
Advanced Pattern: Multiple Aliases

For advanced use cases, you can create multiple aliases for different purposes: 
Channels
├─ Website Widget → Production Alias → Version #5
├─ Zendesk → Production Alias → Version #5
├─ Salesforce → Production Alias → Version #5
└─ Internal Slack → Staging Alias → Version #6 (testing)

Available Versions
├─ Version #6 (Testing in Staging)
├─ Version #5 (Active in Production)
└─ Version #4 (Previous stable version)
Benefits:
  • Test updates on one channel before deploying to all
  • Different versions for internal vs. customer-facing channels
  • Gradual rollout capability
Drawbacks:
  • More complex to manage
  • Risk of configuration drift
  • Need to track multiple active versions

​
Model 4: Guidances, Actions & Knowledge

The Guidances, Actions, and Knowledge model defines how your AI behaves, what it can do, and what it knows. These three components work together within Profiles to create a complete AI configuration that gets versioned and deployed.

​
Overview

Profile (e.g., "v0.5")
├── Guidances (How the AI behaves)
│   └── Instructions + Tool permissions
├── Actions (What the AI can do)
│   └── Tools, MCP servers, Triggers
└── Knowledge (What the AI knows)
    └── Data providers, Sources, Embeddings
Guidance - Behavioral instructions that control how your AI responds Actions - Tools and capabilities the AI can execute Knowledge - Information sources the AI can draw upon

​
Guidances: Behavioral Instructions

Guidances are the rules that control how your AI behaves in different situations. Each guidance is a self-contained instruction set with conditional logic for when it applies.

​
What a Guidance Contains

Instructions - Natural language directions for the AI Tool Permissions - Which actions the AI can use (allowed_tools) Audience Rules - Conditions determining when this guidance applies Active/Draft State - Whether the guidance is live or being tested

​
Data Model Structure

Guidance {
  id: string                           // Unique identifier
  project_id: number                   // Associated project
  name: string                         // Descriptive name
  instructions_template: string        // Markdown instructions
  instructions_template_html: string   // HTML formatted version
  allowed_tools: Array<string>         // Enabled tool names
  audience: AudienceRules             // Conditional targeting
  active: boolean                      // Live or draft
}

​
How Guidances Work

1. Tool Mentioning When you write instructions, reference tools using backticks: 
Use `search_orders` to find the customer's order history.
Then use `create_refund` if the order is within 30 days.
botBrains automatically:
  • Detects tool mentions in your instructions
  • Adds them to allowed_tools
  • Warns if tools are mentioned but not enabled
  • Warns if tools are enabled but not used
2. Audience Targeting Each guidance can have audience rules that determine when it applies:
  • Customer tier (VIP, Free, Enterprise)
  • User attributes (region, language, subscription status)
  • Conversation context (channel, time, labels)
3. Guidance Priority Multiple guidances are evaluated in order. You can drag-and-drop to reorder priority. 4. Active vs Draft
  • Active - Applied in deployed versions
  • Draft - Saved but not applied until activated

​
Practical Example

Guidance: VIP Customer Refunds 
Name: VIP Customer Refund Policy
Active: Yes
Audience: customer_tier = "VIP"

Instructions:
For VIP customers, we offer extended refund windows. Use `search_orders`
to find their order history. Check if the order is within 60 days (not
the standard 30 days). If eligible, use `create_refund` to process the
refund immediately without requiring manager approval.

Always thank VIP customers for their continued business.

Allowed Tools: [search_orders, create_refund]

​
Actions: What the AI Can Execute

Actions are the tools and capabilities your AI can use to accomplish tasks beyond answering questions. Actions are configured at the profile level and made available to guidances.

​
Types of Actions

Built-in Tools
  • Web Search - Search the internet for real-time information
  • Fetch Web Pages - Retrieve content from URLs
  • Offer Handoff - Create email escalations to human support
  • Escalate to Human - Immediately route to support agents
  • Search Knowledge - Query your knowledge base
Search Tables
  • Structured data uploaded to botBrains (CSV, JSON, JSONL)
  • Queryable with filters, ranges, and multi-select
  • Examples: Product catalogs, order histories, FAQ databases
MCP Servers (3rd Party Systems)
  • External integrations via Model Context Protocol
  • Pre-built: Salesforce, HubSpot, Stripe, Shopify, Zapier
  • Custom: Your own APIs and services
  • Can expose multiple tools per server
Triggers
  • Automated actions when conditions are met
  • Types: Block, Assign Label, Unassign Label
  • Executed before AI responds (for security/routing)

​
Data Model Structure

ToolSettings {
  triggers?: Array<Trigger>                    // Event-based automation
  others?: Array<PrebuildToolSettings>         // Built-in tools
  tables?: Array<TableToolSettings>            // Search tables
  mcp_servers?: Array<McpServer>              // External integrations
  toolboxes?: Array<Toolbox>                  // Custom tool collections
}

McpServer {
  server_label: string                         // Display name
  server_url: string                           // MCP endpoint
  authorization: string                        // Auth credentials
  allowed_tools: Array<string>                 // Enabled tool names
  require_approval: "always" | "never"         // User confirmation
  tools: Array<Tool>                           // Available tools
}

​
How Actions Work

1. Tool Configuration Configure tools in Profile > Tools tabs:
  • General Tab - Built-in tools and search tables
  • MCP Servers Tab - External integrations
  • Toolboxes Tab - Custom tool collections
2. Tool Availability Tools configured in Actions become available for Guidances to reference. Each guidance specifies which tools it can use via allowed_tools. 3. Approval Flow For sensitive actions, require user approval:
  • AI determines action is needed
  • Presents action to user with explanation
  • User approves or rejects
  • If approved, action executes and results returned
4. Tool Namespacing MCP server tools are namespaced: ServerName::tool_name Search table tools use simple names: search_products

​
Practical Example

E-commerce Support Bot Actions: Search Table: Orders Database
  • Tool name: search_orders
  • Data: Order ID, customer email, status, date, amount
  • Searchable fields: email, order ID, date range
MCP Server: Stripe Integration
  • Server URL: https://mcp.stripe.com
  • Tools: Stripe::get_payment, Stripe::create_refund
  • Approval: Required for create_refund, not required for get_payment
Built-in: Offer Handoff
  • Enabled for complex shipping issues
  • Creates email draft for support team
Trigger: Auto-label refund requests
  • Event: User message received
  • Condition: Message contains “refund”
  • Action: Assign label “refund-request”

​
Knowledge: What the AI Knows

Knowledge is your AI’s information foundation - the sources it draws upon to provide accurate, grounded responses. Knowledge is versioned alongside your profile configuration.

​
Knowledge Architecture

Data Providers - Sources of content (human, web crawler, Confluence) Sources - Individual documents/pages within providers Snapshots - Versioned states of provider content at build time Chunks - Indexed segments for retrieval Embeddings - Vector representations for semantic search

​
Data Model Structure

DataProvider {
  id: string                          // Unique identifier
  name: string                        // Display name
  project_id: number                  // Associated project
  data_provider_type: "human" | "webcrawler" | "confluence"
  schedule: CronTab | null            // Auto-sync schedule
  definition: CrawlerJobOutput        // Crawl configuration
  audience: AudienceRules             // Audience filtering
}

Source {
  id: number                          // Unique identifier
  name: string                        // Source name
  data_provider_id: string            // Parent provider
  file_type: MimeType                 // Content type
  resource_id: string                 // URL or identifier
  text_bytesize: number               // Content size
  audience_id: string | null          // Audience restriction
}

SourceAttribution {
  source_id: string                   // Source used
  chunk_id: string                    // Specific chunk
  highlight_text: string              // Quoted text
  highlight_text_url: string          // URL to source
}

​
How Knowledge Works

1. Knowledge Retrieval When a user asks a question:
  • System extracts concepts and intent
  • Performs vector similarity search (semantic matching)
  • Retrieves relevant chunks from sources
  • Filters by audience rules
  • Returns attributed sources to AI
2. Knowledge Snapshots Knowledge is versioned:
  • When you build a profile version, current knowledge is captured
  • Deployed versions use the knowledge snapshot from build time
  • Changes to data providers don’t affect deployed versions until rebuild
  • This ensures stability - knowledge doesn’t change mid-conversation
3. Source Attribution Every AI response tracks which sources informed it:
  • Sources Used - Cited in the response
  • Available Sources - Retrieved but not used
  • Users can view, link, and copy source references
4. Knowledge Syncing
  • Web Crawler - Auto-syncs on schedule (daily/weekly)
  • Human/Snippets - Manual creation and updates
  • Confluence - Syncs from connected Confluence spaces

​
Data Provider Types

Human (Snippets)
  • Manually created content
  • Perfect for policies, procedures, key information
  • Created via UI or “Improve Answer” flow
Web Crawler
  • Automatically syncs website content
  • Configurable crawl rules and schedules
  • Tracks changes and updates
Confluence
  • Direct connection to Confluence spaces
  • Syncs documentation automatically

​
Practical Example

SaaS Support Bot Knowledge: Data Provider 1: Help Documentation
  • Type: Web Crawler
  • URL: https://help.example.com
  • Schedule: Daily sync
  • Sources: 120 help articles
  • Audience: All users
Data Provider 2: Enterprise Features
  • Type: Human (Snippets)
  • Sources: 15 manually created snippets
  • Topics: Advanced features, API docs, SSO setup
  • Audience: Enterprise customers only
Data Provider 3: Product Updates
  • Type: Confluence
  • Space: Product Announcements
  • Sources: 45 release notes and updates
  • Audience: All users
Knowledge Snapshot (Dec 1, 2025):
  • 180 total sources
  • 2,450 chunks indexed
  • 2,450 embedding vectors
  • Captured when Profile v0.5 was built

​
How Guidances, Actions, and Knowledge Work Together

These three components form a complete system within each Profile.

​
The Complete Workflow

User Question: "I want a refund for order #12345"
    ↓
[KNOWLEDGE] Retrieve relevant sources
    - Finds "Refund Policy" document
    - Finds "30-Day Window" policy
    - Checks user audience (VIP tier)
    ↓
[GUIDANCE] Evaluate guidance rules
    - Matches "VIP Customer Refund Policy" guidance
    - Instructions say: use search_orders, check 60-day window
    - Allowed tools: [search_orders, create_refund]
    ↓
[ACTIONS] Execute permitted tools
    - Calls `search_orders` with order ID
    - Verifies order is within 60 days
    - Calls `create_refund` (requires approval)
    ↓
AI Response with source attribution
    - "I found your order #12345. As a VIP customer, you're
      eligible for our extended 60-day refund window. I can
      process your refund now."
    - [Approve Refund] button shown to user
    - Sources: "Refund Policy", "VIP Customer Benefits"

​
Integration Points

Within Profiles A Profile bundles all three: 
Profile v0.5
├── System Message & LLM Settings
├── Guidances (3 rules)
│   ├── VIP Refund Policy
│   ├── Technical Support
│   └── Sales Inquiries
├── Tools (Actions)
│   ├── search_orders (Search Table)
│   ├── Stripe (MCP Server)
│   └── Offer Handoff (Built-in)
└── Knowledge Snapshot
    ├── Help Documentation (120 sources)
    ├── Enterprise Features (15 sources)
    └── Product Updates (45 sources)
Deployment & Versioning When you build a profile:
  • All guidance rules captured (current state)
  • All knowledge sources and embeddings captured (snapshot)
  • All action configurations captured
  • Creates immutable deployment version
When you deploy:
  • Entire package (Guidance + Knowledge + Actions) goes live
  • All connected channels use this version
  • Changes require rebuilding and redeploying

​
User Interactions

In Conversations
  1. User asks question
  2. Knowledge retrieval finds relevant sources
  3. Guidance rules evaluate based on audience
  4. AI uses allowed tools from matching guidance
  5. Response generated with source attributions
  6. Knowledge sidebar shows which sources were used
In Profile Editor
  1. Guidance Tab - Edit rules, preview responses
  2. Tools Tabs - Configure actions (MCP servers, tables)
  3. Knowledge - Managed in Data Providers section
  4. Build - Create new version with all three components
  5. Deploy - Publish to channels
“Improve Answer” Feature When users want to improve an AI response:
  1. Open Knowledge Sidebar
  2. View sources used and available
  3. Add snippet to knowledge
  4. Edit guidance instructions
  5. Rebuild and redeploy

​
Why This Structure Matters

Complete AI Configuration Guidances, Actions, and Knowledge together define everything your AI needs: how to behave, what to do, and what to know. Versioned Together All three components are captured in each deployment version, ensuring consistency and enabling complete rollback. Separation of Concerns
  • Guidances = Behavior and instructions
  • Actions = Capabilities and integrations
  • Knowledge = Information and sources
Each can be modified independently, then bundled into a new version. Audience-Aware All three support audience targeting:
  • Guidances apply to specific user segments
  • Actions can require different approvals per audience
  • Knowledge can be filtered by audience
Continuous Improvement The “Improve Answer” workflow connects all three:
  • Users identify gaps in responses
  • Add knowledge (snippets)
  • Adjust guidance (instructions)
  • Enable actions (tools)
  • Rebuild and deploy

​
Practical Example: E-commerce Support

Project: Acme Store Support Bot Guidances (3 rules): 1. VIP Order Support
  • Audience: customer_tier = “VIP”
  • Instructions: Provide white-glove service, extended windows
  • Tools: [search_orders, create_refund, assign_vip_agent]
2. Standard Customer Support
  • Audience: customer_tier = “Standard”
  • Instructions: Follow standard policies, offer self-service
  • Tools: [search_orders, offer_handoff]
3. Technical Issues
  • Audience: All customers
  • Instructions: Troubleshoot, escalate if needed
  • Tools: [search_knowledge, create_ticket, escalate_to_human]
Actions: Search Tables:
  • Orders Database (search_orders)
  • Product Catalog (search_products)
MCP Servers:
  • Stripe: Payment and refund tools
  • Zendesk: Ticket creation and management
Built-in Tools:
  • Web Search (for tracking numbers)
  • Offer Handoff (for complex cases)
Triggers:
  • Auto-label “refund” messages
  • Block spam users
Knowledge: Data Provider: Help Center
  • Type: Web Crawler
  • 150 help articles
  • Daily sync
  • Audience: All
Data Provider: VIP Resources
  • Type: Human (Snippets)
  • 20 VIP-specific policies
  • Audience: VIP customers
Data Provider: Product Info
  • Type: Web Crawler
  • Product pages and specs
  • Weekly sync
  • Audience: All
Deployment:
  • Built as Profile v0.8
  • Deployed to Production alias
  • All channels (Website, Zendesk) use this version
  • Version includes all guidance, actions, knowledge from Dec 1, 2025

​
Best Practices

For Guidances:
  • Write instructions as if training a team member
  • Use specific, actionable language
  • Reference tools naturally in instructions
  • Test as draft before activating
  • Order by priority (most specific first)
For Actions:
  • Only enable tools AI genuinely needs
  • Require approval for data-modifying actions
  • Use triggers for security and moderation
  • Test MCP connections before deploying
  • Monitor tool usage and performance
For Knowledge:
  • Use snippets for policies and precision content
  • Keep crawler-based knowledge updated
  • Monitor “Improve Answer” to find gaps
  • Use audience filtering for segment-specific knowledge
  • Always rebuild after knowledge changes
For Integration:
  • Build versions when ready to test
  • Use staging alias for validation
  • Monitor metrics after deploying
  • Keep version history for rollback
  • Document changes between versions

Guidance

Deep dive into writing effective guidance instructions

Actions

Complete guide to configuring tools and integrations

Knowledge

Managing data providers and knowledge sources

​
How the Four Models Work Together

The four data models combine to support your complete AI customer service workflow.

​
Complete System View

Organization: Acme Corp
│
├─ Project: Customer Support
│   │
│   ├─ [Model 1: Organization]
│   │   └─ Configuration, Team Access, Billing
│   │
│   ├─ [Model 2: User, Conversation, Messages]
│   │   └─ User Pool: Customers
│   │       ├─ User: john@example.com
│   │       │   └─ Conversations #1, #2, #3
│   │       └─ User: sarah@business.com
│   │           └─ Conversations #4, #5
│   │
│   ├─ [Model 3: Channel, Alias, Deployment]
│   │   ├─ Deployments
│   │   │   ├─ Version #5 (Active)
│   │   │   ├─ Version #4
│   │   │   └─ Version #3
│   │   ├─ Aliases
│   │   │   └─ Production → Version #5
│   │   └─ Channels
│   │       ├─ Website Widget → Production
│   │       ├─ Zendesk → Production
│   │       └─ Salesforce → Production
│   │
│   └─ [Model 4: Guidances, Actions & Knowledge]
│       ├─ Profile v0.5
│       │   ├─ Guidances (3 rules)
│       │   │   ├─ VIP Refund Policy
│       │   │   ├─ Technical Support
│       │   │   └─ Sales Inquiries
│       │   ├─ Actions (Tools)
│       │   │   ├─ Search Tables
│       │   │   ├─ MCP Servers
│       │   │   └─ Built-in Tools
│       │   └─ Knowledge Snapshot
│       │       ├─ Help Documentation (120 sources)
│       │       ├─ Enterprise Features (15 sources)
│       │       └─ Product Updates (45 sources)
│
└─ Project: Sales Assistant
    └─ [Same structure as above, completely independent]

​
Typical Workflow

1. Setup (Model 1: Organization)
  • Create organization account
  • Set up billing
  • Create first project
  • Invite team members
2. Configuration (Model 4: Guidances, Actions & Knowledge)
  • Add knowledge sources (Data Providers)
  • Write guidance instructions
  • Configure tools and actions (Search Tables, MCP Servers)
  • Configure triggers for automation
3. Build & Deploy (Model 3: Channel)
  • Build deployment version (captures Guidances, Actions, Knowledge)
  • Create Production alias
  • Set alias to point to version
  • Configure channels (website, integrations)
  • Connect channels to Production alias
4. Usage (Model 2: User, Conversation, Messages)
  • Customers interact via channels
  • Users are created/identified automatically
  • Conversations are tracked
  • Messages are stored and analyzed
5. Iteration (All Models)
  • Review analytics and conversations (Model 2)
  • Make improvements to guidance/knowledge (Model 4)
  • Build new version (Model 3)
  • Update Production alias (Model 3)
  • Monitor impact (Model 2)

​
Cross-Model Relationships

Projects tie everything together Projects contain deployments (Channel Model) and user pools (User Model) while being owned by organizations (Organization Model). Conversations link users and channels Each conversation belongs to a user (User Model) and references which alias/channel it came from (Channel Model). Analytics aggregate across models Project analytics combine data from users, conversations, messages (User Model) and segment by channel/version (Channel Model).

​
Summary

botBrains uses four distinct data models to organize your AI customer service operations:

​
Model 1: Organization & Projects

Organization - Your company’s account, managing billing and team access Projects - Independen AI agents with their own configuration and knowledge Why it matters: Clean separation, easy scaling, centralized billing

​
Model 2: User, Conversation, Messages

User - A person who interacts with your AI (identified or anonymous) Conversation - A session of interaction, owned by exactly one user Messages - Individual exchanges within conversations Why it matters: Complete customer context, persistent identity, rich analytics

​
Model 3: Channel, Alias, Deployment

Channel - Where users interact (Website, Zendesk, Salesforce, Slack, WhatsApp) Alias - A pointer to a specific deployment version Deployment (Version) - Immutable snapshot of AI configuration and knowledge Why it matters: Safe updates, version control, easy rollback, consistent deployment

​
Model 4: Guidances, Actions & Knowledge

Guidances - Behavioral instructions that control how your AI responds Actions - Tools and capabilities the AI can execute (Search Tables, MCP Servers, Triggers) Knowledge - Information sources the AI draws upon (Data Providers, Sources, Embeddings) Why it matters: Complete AI configuration, versioned together, separation of concerns, audience-aware

​
Getting Started

Day 1: Create a project (Model 1: Organization) Day 1: Add knowledge and guidance (Model 4: Guidances, Actions & Knowledge) Day 1: Build first deployment (Model 3: Channel) Day 1: Deploy to website widget (Model 3: Channel) Day 2+: Customers interact, users created (Model 2: User) Ongoing: Review analytics, improve, rebuild, redeploy (All Models)

Users

Deep dive into user management, identification, and segmentation

Deployments

Complete guide to building and managing deployment versions

Integration Channels

Connect your AI to website, Zendesk, Salesforce, Slack, and more

Versioning

Detailed information on version control and knowledge snapshots

Audiences

Create user segments for personalized AI responses

Topics

Understand automatic conversation classification and analytics
 Understanding the data model enables you to organize your AI operations effectively, deliver personalized customer experiences, and scale from a single project to complex multi-brand deployments.