Skip to main content

​
Project Settings

Project settings define the foundational configuration for you AI agent - from how it identifies itself to customers, to the support channels you provide. Properly configured project settings ensure seamless customer experiences and smooth handoffs when human support is needed.

​
Why Project Settings Matter

Your project settings shape critical customer-facing elements: Brand Consistency - Configure how your AI identifies itself across all customer touchpoints, maintaining consistent branding. Seamless Handoffs - Define where escalations go and how customers reach your support team when AI can’t help. Context for AI - Provide your AI with essential information about your business that informs its responses. Integration Foundation - URLs and contact information enable proper integration with external systems and support workflows. Team Organization - Clear project settings help teams manage multipl AI agents for different products or customer segments.

​
Understanding Project Settings

Project settings are divided across several configuration areas, accessible from the project settings overview. Each area serves a specific purpose in defining your AI’s identity and behavior.

​
Settings Overview

Navigate to Settings in your project to access all configuration options. The settings are organized into logical groups: Configuration - Core project settings, audiences, and automation triggers Communication - Handoff settings, notifications, and alerts Team & Access - Team members, roles, permissions, and API keys Data - Labels, exports, and data management
Project settings are project-specific. Each project (AI assistant) has independent configuration, allowing you to manage multiple assistants with different settings.

​
Core Project Configuration

The main project settings control your AI’s basic identity and associated URLs.

​
Project Description

An optional internal description to help your team identify and organize projects. Purpose:
  • Internal reference only (not shown to customers)
  • Helps distinguish between multiple projects
  • Useful for team collaboration and project management
Example: 
Customer support AI for our e-commerce platform, handles order inquiries,
shipping questions, and product information.
When to use:
  • Managing multiple projects or product lines
  • Different teams working on variou AI agents
  • Onboarding new team members who need context

​
Website URL

The primary URL of your website or application. Purpose:
  • Provides context about your business
  • Used in some integration scenarios
  • Helps AI understand your domain context
Format: Full URL including protocol 
https://www.example.com
https://app.example.com
https://shop.example.com
Best practices:
  • Use your main customer-facing URL
  • Include the protocol (https://)
  • Avoid trailing slashes
  • Use production URL, not staging or development
If you have multiple websites (marketing site, web app, help center), use the URL most relevant to customer support interactions - typically your help center or main application.

​
Support Website URL

The URL where customers can find additional help resources. Purpose:
  • Directs customers to self-service resources
  • Referenced in certain escalation scenarios
  • Links to knowledge base or help documentation
Common examples: 
https://help.example.com
https://support.example.com
https://docs.example.com
https://www.example.com/help
When to configure:
  • You maintain a separate help center or knowledge base
  • Customers can find additional resources beyond AI
  • Integration workflows reference support documentation
Difference from Website URL:
  • Website URL: Your main business site
  • Support Website URL: Specific help/documentation site
Both URLs are optional. However, if you use features that reference these URLs (certain integrations or custom guidance), ensure they’re configured and accessible.

​
Handoff Configuration

Handoff settings control how customers are transferred to human support when your AI can’t help. These settings are critical for the escalation experience.

​
Project Name

The name shown to customers when interacting with your AI and in handoff communications. Where it appears:
  • Widget welcome messages
  • Email handoff subject lines
  • Integration channel displays
  • Customer-facing communications
Naming guidelines:
  • Clear and recognizable to customers
  • Matches your brand name or product name
  • Professional and customer-appropriate
  • Concise (1-4 words typically)
Good examples: 
Acme Support
TechCorp Customer Service
ShopEasy Help
CloudApp Assist
Avoid: 
Test Bot
My AI
Support AI v2
Internal Project 123
Use a name customers would recognize from your brand. If they see “Acme Support” in an email subject, they should immediately know it’s from your company.

​
Support Email

The email address where handoff messages are sent when customers need human help. Purpose:
  • Receives escalation emails from AI
  • Primary contact for customer handoffs
  • Critical for the offer_handoff and escalate_to_human tools
Requirements:
  • Must be actively monitored
  • Should reach your support team
  • Valid email format
Configuration options: Individual email: 
support@example.com
help@example.com
customerservice@example.com
Team inbox: 
team@support.example.com
tickets@example.com
Ticketing system email: 
helpdesk@example.zendesk.com
support-12345@example.freshdesk.com
This email must be actively monitored. Customers expect responses after handoff. Configure your support team to check this inbox regularly and respond within your SLA.

​
How Handoffs Work

When a customer is handed off to human support: 1. AI Determines Escalation Needed
  • Based on guidance rules and tools enabled
  • Uses offer_handoff or escalate_to_human tool
2. Email is Composed
  • Subject: [Project Name] Support Request: [Issue Summary]
  • Body includes customer question and conversation context
  • Customer’s email included for follow-up
3. Email Sent to Support Email
  • Arrives in configured support inbox
  • Contains all necessary context
  • Conversation marked as “escalated” in botBrains
4. Support Team Responds
  • Support team receives complete context
  • Can reply directly to customer
  • Customer doesn’t need to repeat information
Example handoff email: Subject: 
[Acme Support] Support Request: Billing question about annual plan
Body: 
A customer has requested human support through ou AI agent.

Customer Email: user@example.com

Issue Summary:
The customer is asking about upgrading from monthly to annual billing
and whether the 20% discount is automatically applied at checkout.

Customer's Message:
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 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?

Conversation History: [Link to full conversation]
For detailed escalation configuration including guidance rules and tool setup, see Escalations.

​
Accessing Project Settings

Project settings are accessed through multiple paths depending on what you’re configuring.

​
Settings Overview Page

Navigate to Settings from your project sidebar to see all available settings grouped by category: From the settings overview, you can access:
  • Audiences
  • Triggers (automation)
  • Handoffs (project name and support email)
  • Notifications
  • Team management
  • Roles and permissions
  • API Keys
  • Labels
  • Data Export
Direct settings:
  • Project description
  • Website URL
  • Support website URL
Settings pages use breadcrumb navigation: 
Project Name > Settings > [Specific Setting]
Use breadcrumbs to navigate back or understand your location in the settings hierarchy.

​
Organization Settings

Project settings are separate from organization settings. To access organization-wide configuration: From Project Settings: Click “Go to Organization Settings” in the page header Organization settings include:
  • Organization name and details
  • Billing and subscription
  • Default settings for new projects
  • Organization-level security policies
See Organization Settings for organization-wide configuration.

​
Common Configuration Scenarios

​
Setting Up a New Project

When creating a new project, configure settings in this order: 1. Project Identity
  • Set project name (customer-facing)
  • Add internal description (team reference)
  • Configure website URLs
2. Handoff Configuration
  • Configure support email
  • Verify email is monitored
  • Test handoff flow
3. Team Access
  • Invite team members
  • Assign appropriate roles
  • Configure permissions
4. Audiences and Targeting
  • Define customer segments if needed
  • Create audience rules
  • Test audience targeting
5. Automation
  • Set up triggers if needed
  • Configure notifications
  • Test automation workflows
6. Integration Preparation
  • Generate API keys if using API
  • Document settings for integrations
  • Review security settings

​
Multi-Product Support

If you support multiple products or customer segments: Option 1: Separate Projects Create individual projects for each product: 
Project: "ProductA Support"
- Description: Customer support for Product A
- Website URL: https://producta.example.com
- Support Email: producta-support@example.com

Project: "ProductB Support"
- Description: Customer support for Product B
- Website URL: https://productb.example.com
- Support Email: productb-support@example.com
Benefits:
  • Independent knowledge bases
  • Separate analytics
  • Product-specific guidance
  • Different team access
Option 2: Single Project with Audiences Use one project with audience targeting: 
Project: "Acme Product Suite"
- Description: Unified support for all products
- Website URL: https://www.acme.com
- Support Email: support@acme.com
- Audiences: ProductA Users, ProductB Users
Benefits:
  • Unified analytics
  • Shared knowledge where relevant
  • Simpler team management
  • Cross-product context
Use separate projects when products have very different support needs, knowledge bases, or teams. Use audiences when products share significant knowledge and support processes.

​
E-commerce Configuration

Example setup for online store: Project Name: “ShopEasy Customer Service” Description: 
Customer support for ShopEasy e-commerce platform. Handles order
inquiries, shipping questions, returns, product information, and
account management.
Website URL: https://www.shopeasy.com Support Website URL: https://help.shopeasy.com Support Email: support@shopeasy.com Key considerations:
  • Support email should integrate with order management system
  • Website URL helps AI understand product context
  • Support website URL points to return policies, shipping info

​
SaaS Application Configuration

Example setup for software service: Project Name: “CloudApp Support” Description: 
Technical support AI for CloudApp SaaS platform. Handles account
questions, billing inquiries, feature guidance, and technical
troubleshooting.
Website URL: https://app.cloudapp.io Support Website URL: https://docs.cloudapp.io Support Email: support@cloudapp.io Key considerations:
  • Support email might create tickets in help desk
  • Docs URL points to technical documentation
  • App URL is where customers access the service

​
Service Business Configuration

Example setup for service company: Project Name: “Acme Consulting” Description: 
Client support for Acme Consulting services. Handles appointment
scheduling, service inquiries, billing questions, and general
information.
Website URL: https://www.acmeconsulting.com Support Website URL: https://www.acmeconsulting.com/faq Support Email: hello@acmeconsulting.com Key considerations:
  • Support email goes to main business email
  • FAQ URL provides self-service information
  • Name reflects business brand

​
Project Lifecycle Management

​
Updating Project Settings

Project settings can be updated at any time without disrupting active conversations. What updates immediately:
  • Project name (affects new conversations)
  • Support email (affects new handoffs)
  • Website URLs (affects new references)
What doesn’t affect active conversations:
  • Changing project name doesn’t update ongoing conversations
  • Support email changes apply to new handoffs only
  • Description is internal only
Best practices for updates:
  • Test handoff flow after changing support email
  • Communicate name changes to your team
  • Update documentation when URLs change
  • Verify integrations after configuration changes

​
Archiving Projects

Currently, botBrains doesn’t have a dedicated “archive” feature, but you can effectively archive projects: To archive a project:
  1. Deactivate all deployments - Remove from production
  2. Remove team member access - Limit to admins only
  3. Update description - Add “[ARCHIVED]” prefix
  4. Document reason - Note why archived and when
Example archived project: 
Name: ProductX Support
Description: [ARCHIVED 2024-11-30] Product X was discontinued.
Historical data retained for compliance.

​
Deleting Projects

Project deletion is a destructive action. All project data will be permanently removed, including conversations, knowledge, guidance, and analytics.
Before deleting a project:
  1. Export critical data - Use Data Export to save conversations
  2. Verify all team members agree - Confirm deletion is appropriate
  3. Check compliance requirements - Ensure data retention policies allow deletion
  4. Remove integrations - Disconnect from external systems first
To delete a project:
  1. Navigate to Settings in your project
  2. Scroll to the Danger Zone section
  3. Click Delete Project
  4. Type delete to confirm
  5. Confirm deletion in dialog
What is deleted:
  • All conversations and messages
  • Knowledge sources and snippets
  • Guidance and profile versions
  • Deployments and integrations
  • Analytics and metrics
  • Team member access (project-specific)
What is NOT deleted:
  • Organization account
  • Other projects
  • Billing information
  • Organization team members
Once a project is deleted, the action cannot be undone. The data cannot be recovered. Only proceed if you’re absolutely certain.

​
Integration with Other Settings

Project settings interact with other configuration areas:

​
Handoff Settings Integration

Project Name and Support Email (configured in Settings → Handoffs) are used by:
  • Escalation tools (offer_handoff, escalate_to_human)
  • Email notifications
  • Integration handoff flows
  • Customer-facing messages

​
Audience Targeting

Website URL and Support Website URL can be used in:
  • Audience rule conditions
  • Custom guidance referencing your domain
  • Integration context

​
API Keys

Project-level API keys (configured in Settings → API Keys) inherit:
  • Project scope
  • Access to project data only
  • Project-specific permissions
See API Keys for programmatic access configuration.

​
Notifications

Support Email is separate from notification preferences:
  • Support email receives customer handoffs
  • Notification emails go to individual team members
  • Configure separately in Settings → Notifications
See Notifications for alert configuration.

​
Best Practices

​
Choose Recognizable Names

Customer Recognition

Use project names that customers would recognize. If it appears in an email or widget, customers should know it’s from your company.

Consistency

Match your existing brand voice. If customers know you as “Acme Support” in other channels, use that name in botBrains too.

​
Monitor Support Email

Active Monitoring

The support email must be actively checked. Customers expect responses after escalation. Set up email rules, assign team members, or integrate with your ticketing system.

Response SLAs

Define response time expectations for handoff emails. Communicate these to customers during escalation.

​
Maintain Accurate URLs

Production URLs

Always use production URLs, not development or staging. These URLs may be referenced in customer conversations.

Keep Updated

When you change domain names or URL structure, update project settings to match.

​
Document Configuration

Team Documentation

Document why certain settings are configured. This helps when team members change or you need to modify settings later.

Configuration Standards

If you manage multiple projects, establish standards for naming, descriptions, and URL formats.

​
Troubleshooting

​
Handoff Emails Not Received

Problem: Support team doesn’t receive handoff emails Check:
  • Support email address is correct in Settings → Handoffs
  • Email isn’t caught by spam filters - whitelist botBrains sender
  • Email server accepts emails from external sources
  • Test with personal email to verify delivery
  • Check email server logs for rejected messages
Solutions:
  • Verify email address spelling
  • Add botBrains to email allowlist
  • Test handoff flow with test conversation
  • Configure email forwarding rules if needed

​
Wrong Project Name in Customer Messages

Problem: Customers see outdated or wrong project name Check:
  • Project name in Settings → Handoffs is current
  • Clear browser cache if using web widget
  • Rebuild and deploy latest profile version
  • Check if custom guidance overrides project name
Solutions:
  • Update project name in Handoffs settings
  • Rebuild profile to pick up latest settings
  • Clear customer browser cache/cookies
  • Verify no custom guidance contradicts project name

​
URLs Not Working in Integrations

Problem: Integrations can’t access configured URLs Check:
  • URLs include protocol (https://)
  • URLs are accessible publicly (not behind firewall)
  • No typos in URL configuration
  • URLs resolve correctly (test in browser)
Solutions:
  • Add https:// protocol if missing
  • Verify URLs are publicly accessible
  • Test URLs in incognito browser
  • Update URLs if domain changed

​
Cannot Delete Project

Problem: Delete button disabled or option not visible Check:
  • You have appropriate permissions (Owner or Admin role)
  • Feature flag for deletion is enabled
  • No active deployments are blocking deletion
Solutions:
  • Contact organization owner for permission
  • Deactivate all deployments first
  • Check with botBrains support if deletion unavailable

​
Multiple Projects Getting Confused

Problem: Team members confused about which project is which Solutions:
  • Use distinctive project names
  • Add detailed descriptions
  • Document project purpose in team wiki
  • Create naming convention (e.g., “[Product] Support”)
  • Use different support emails for each project

​
Security Considerations

​
Support Email Security

Email access:
  • Limit access to support email inbox
  • Use team inbox rather than personal email
  • Configure email encryption if handling sensitive data
  • Audit who can access handoff emails
Data in emails:
  • Handoff emails contain conversation context
  • May include customer personal information
  • Subject to data protection regulations (GDPR, CCPA)
  • Ensure email system complies with retention policies

​
URL Configuration

Public URLs:
  • Website URLs should be publicly accessible
  • Don’t configure internal/private URLs
  • Avoid exposing staging environments
  • Use HTTPS for security

​
Project Access

Team permissions:
  • Limit project settings access to admins
  • Regular team members don’t need settings access
  • Use roles to control who can modify settings
  • Audit settings changes regularly
See Roles & Permissions for access control.

​
Next Steps

Now that you understand project settings:

Configure Handoffs

Set up handoff settings and configure escalation tools for smooth transitions to human support

Manage Your Team

Invite team members and configure their access to projects

Set Up Notifications

Configure email notifications for important project events

Organization Settings

Configure organization-wide settings and billing
 Proper project configuration ensures you AI agent has the identity and support infrastructure needed to deliver excellent customer experiences. Take time to configure these settings thoughtfully - they form the foundation of your AI’s customer interactions.