Skip to main content

​
Team Management

Team management in botBrains enables you to build collaborative workflows around you AI agents. Whether you’re a solo founder expanding to your first support hire, or an enterprise managing dozens of projects across departments, botBrains provides the tools to invite team members, assign appropriate access levels, and maintain security while enabling efficient collaboration.

​
Why Team Management Matters

Effective team collaboration transforms AI development from a solo endeavor into a coordinated team effort:

​
Scale Support Operations

As your business grows, you need more people reviewing conversations, updating knowledge, and configuring AI behavior. Team management lets you distribute these responsibilities without bottlenecks or single points of failure.

​
Separate Responsibilities Safely

Different team members need different capabilities. Support agents review conversations and add knowledge. Developers configure integrations and deployments. Executives monitor performance. Team management ensures each person has exactly the access they need without exposing them to actions that could break production systems.

​
Enable Cross-Functional Workflows

Moder AI agents require input from multiple departments: product teams define user flows, support teams identify knowledge gaps, engineers integrate with backend systems, and QA teams validate responses. Organized team management facilitates these cross-functional collaborations.

​
Maintain Compliance and Audit Trails

For regulated industries or enterprise customers, you need to demonstrate who has access to customer data, who made configuration changes, and when access was granted or revoked. Team management provides the foundation for these compliance requirements.

​
Onboard New Members Quickly

New team members need to contribute on day one. Clear role assignments, pending invitation tracking, and pre-configured permission sets let new hires get started immediately without lengthy access request processes.

​
Understanding Organization vs. Project Teams

botBrains uses a two-level team structure that mirrors how real companies organize:

​
Organization Team

Your organization team includes everyone who has access to your botBrains account. This is typically your company, department, or business unit. Organization members can:
  • Access organization-wide settings and billing (if they have sufficient organization role)
  • Create new projects (if they have Organization Owner or Admin role)
  • View projects they’ve been assigned to
  • Manage team members (if they have Organization Owner or Admin role)
When to use organization-level team management:
  • Inviting someone to your company’s botBrains account for the first time
  • Assigning baseline access levels that apply across all projects
  • Managing billing and subscription
  • Removing team members who leave your company

​
Project Teams

Eac AI agent project has its own team, which is a subset of your organization team. Project teams control who can access specifi AI agents. Project team members can:
  • Access only the projects they’ve been assigned to
  • Have different permission levels in different projects
  • Collaborate on project-specific tasks
When to use project-level team management:
  • Giving someone access to a specifi AI agent
  • Restricting access to production vs. development projects
  • Assigning different permissions for different projects (e.g., admin in dev, viewer in production)
  • Creating project-specific teams (marketing team for Marketing Bot, support team for Support Bot)
Every team member has both an organization role and a project role for each project they can access. Your effective permissions are the combination of both roles. See Roles and Permissions for details on how these combine.

​
Inviting Team Members

​
Organization-Level Invitations

Invite people to join your botBrains organization:
1

Navigate to Organization Team Settings

Go to Organization → Settings → Team or click Settings in the sidebar and select Team
2

Switch to Invitations Tab

Click the Invitations tab to see pending invitations (or stay on Members to see current team)
3

Click Invite User

Click the Invite User button in the top right
4

Enter Email Addresses

Type email addresses in the email field. Press space or enter after each email to add multiple recipients
5

Select Organization Role

Choose the appropriate organization role: Organization Owner, Organization Admin, or Organization Member (recommended default)
6

Send Invitations

Click Send Invitations to email invitation links to all recipients
What happens next:
  1. Recipients receive email invitations with a unique join link
  2. Recipients create a botBrains account or sign in with existing account
  3. Upon accepting, recipients automatically join your organization with the assigned role
  4. New members appear in the Members tab and can immediately access permitted projects
You can paste multiple email addresses at once. The invite dialog automatically extracts email addresses from pasted text, making it easy to invite entire teams by copying from spreadsheets or contact lists.
Invitation Best Practices: Use Organization Member as default - Assign Organization Member role to 90% of your invitees. This minimal baseline access lets you control their actual permissions through project-specific roles. Only assign Organization Admin or Owner when someone truly needs organization-wide access. Include context in follow-up - The automated invitation email is generic. Send a follow-up message explaining what projects they’ll be working on and what their initial responsibilities are. Track acceptance - Check the Invitations tab to see who has accepted invitations. Follow up with people who haven’t accepted after a few days.

​
Project-Level Invitations

Invite people to join a specific project (they must already be organization members or you can invite them to both simultaneously):
1

Navigate to Project Team Settings

Go to Project → Settings → Team for the specific project
2

Switch to Invitations Tab

Click the Invitations tab
3

Click Invite User

Click Invite User button
4

Enter Email Addresses

Type email addresses (existing organization members or new people)
5

Select Project Role

Choose the project role: Project Owner, Project Admin, Project Member, Project Viewer, or a custom role
6

Send Invitations

Click Send Invitations
Inviting new people directly to projects: When you invite someone to a project who isn’t yet an organization member, botBrains automatically:
  1. Creates an organization invitation with Organization Member role
  2. Creates a project invitation with your selected project role
  3. Sends a single email invitation
  4. Upon acceptance, grants both organization access and project access
The Team Settings page includes a “Which Role should I choose?” link that provides guidance on selecting appropriate roles for common team member types. Use this if you’re unsure which role to assign.

​
Bulk Invitations

Invite multiple people with the same role efficiently: Method 1: Multi-email input
  1. Click Invite User
  2. Type or paste multiple emails in the email field
  3. Press space or enter after each email
  4. All emails appear as badges in the field
  5. Select one role that applies to everyone
  6. Send invitations
Method 2: URL pre-fill parameters You can create invitation links that pre-populate email addresses and roles: 
Organization invitation:
/settings/team?invite=user1@example.com&invite=user2@example.com&invite_role=o_member

Project invitation:
/{projectId}/settings/team?invite=user1@example.com&invite=user2@example.com&invite_role=p_member
This is useful for:
  • Creating invitation links in onboarding documentation
  • Automating invitations from other systems
  • Deep-linking from admin interfaces

​
Managing Pending Invitations

Track and manage invitations before they’re accepted: View Pending Invitations: Navigate to the Invitations tab at organization or project level to see:
  • Email address of invitee
  • Assigned role
  • Invitation sent date
  • Expiration date
  • Current status (pending, accepted, expired)
Revoke Invitations:
  1. Find the invitation in the Invitations table
  2. Click the trash icon in the Actions column
  3. Confirm revocation
Why revoke invitations:
  • Employee offer was rescinded before acceptance
  • Wrong email address was entered
  • Need to change assigned role (revoke and re-invite with correct role)
  • Invitation sent to wrong person
Once an invitation is accepted, it disappears from the Invitations tab and the user appears in the Members tab. You cannot “un-accept” an invitation - you must remove the member from the organization or project.

​
Managing Existing Team Members

​
Viewing Team Members

Organization Members:
  1. Go to Organization → Settings → Team
  2. Members tab shows all organization members with:
    • Name and profile photo
    • Email address
    • Organization role
    • Join date
    • Actions (change role, remove member)
Project Members:
  1. Go to Project → Settings → Team
  2. Members tab shows all project members with:
    • Name and profile photo
    • Project role (primary column)
    • Organization role (for context)
    • Email address
    • Join date
    • Actions (change role)
When viewing a project’s team page, you see both the project role and organization role for each member. This helps you understand why someone might have more access than expected - they may have a permissive organization role that overrides project restrictions.

​
Changing Team Member Roles

Adjust access levels as responsibilities change: Change Organization Role:
  1. Navigate to Organization → Settings → Team → Members
  2. Find the member in the table
  3. Click the role dropdown in their row
  4. Select new organization role
  5. Change takes effect immediately
Change Project Role:
  1. Navigate to Project → Settings → Team → Members
  2. Find the member in the table
  3. Click the Project Role dropdown (left column)
  4. Select new project role or “No Project Role” to remove access
  5. Change takes effect immediately
Understanding the role change interface:
  • At organization level, you can only modify organization roles
  • At project level, you can modify project roles
  • Organization roles shown in project views are read-only - navigate to organization settings to change them
  • Use “Go to Organization Roles” / “Go to Project Roles” buttons to quickly switch between levels

​
Permission Conflict Warnings

botBrains warns you when organization roles will override project role restrictions: When you’ll see a warning: You assign a restrictive project role (like Project Viewer) to someone who has a permissive organization role (like Organization Admin). What the warning shows:
  • How many permissions the user retains through their organization role
  • List of specific permissions that will be retained
  • Recommendation to demote organization role to Organization Member
Example warning: 
Sarah Chen will retain access to 12 permissions that would otherwise
be removed through their organization role (Organization Admin).
Consider demoting their organization role to Organization Member to
constrain access.

Retained permissions:
- Project Update
- Deployment Create
- Deployment Update
- Knowledge Write
- Conversation Write
- (+ 7 more)
Your options:
  1. Proceed anyway - User keeps broad access through organization role
  2. Cancel - Reconsider the role assignment
  3. Demote organization role first - Change to Organization Member, then assign restrictive project role
This warning only appears when downgrading project roles. When assigning roles to new members, the warning appears during role creation in the RoleSheet dialog if the new role has fewer permissions than existing users’ organization roles.

​
Removing Team Members

Remove access when team members leave or no longer need access to specific projects: Remove from Organization (removes from all projects):
  1. Navigate to Organization → Settings → Team → Members
  2. Find the member in the table
  3. Click the trash icon in the Actions column
  4. Confirm removal in the dialog
Result:
  • User immediately loses access to all projects
  • User cannot sign into botBrains
  • User’s API keys are revoked
  • Conversation history and changes remain (attributed to the removed user)
Remove from Specific Project (keep in organization):
  1. Navigate to Project → Settings → Team → Members
  2. Find the member in the table
  3. Click the Project Role dropdown
  4. Select “No Project Role”
Result:
  • User loses access to this project only
  • User retains access to other projects
  • User remains in organization
Organization removal is immediate and irreversible. The user cannot access botBrains or recover their settings. If they need access again, you must send a new invitation.
When to remove vs. downgrade:
  • Remove entirely: Employee left company, contractor engagement ended, account compromised
  • Remove from project: Team member moved to different projects, temporary access ended
  • Downgrade role: Changed responsibilities but still needs access, reduce to viewer for departing employee during notice period
Use the navigation buttons to move between team management levels: From Organization Team Page:
  • Click “Go to Project Roles” dropdown button
  • Select which project to manage
  • Jumps to that project’s team page
  • Shows project-specific roles and both organization + project roles for context
From Project Team Page:
  • Click “Go to Organization Roles” button
  • Jumps to organization team page
  • Shows organization-wide roles only
This navigation helps you:
  • Quickly audit a user’s access across organization and projects
  • Fix permission conflicts by adjusting the appropriate level
  • Understand why someone has unexpected access (check organization role)

​
Working with Roles

​
Understanding Available Roles

botBrains provides built-in roles and supports custom roles: Organization Roles (built-in only):
  • Organization Owner (o_owner) - Complete control, billing access
  • Organization Admin (o_admin) - Full project access, no billing changes
  • Organization Member (o_member) - No baseline permissions, controlled by project roles
Project Roles (built-in):
  • Project Owner (p_owner) - Complete project control
  • Project Admin (p_admin) - Full access except project deletion
  • Project Member (p_member) - Read/write access without admin capabilities
  • Project Viewer (p_viewer) - Read-only access
Custom Project Roles: Create specialized roles with precise permission combinations tailored to your workflow. See Roles and Permissions for detailed descriptions of each role and their capabilities.

​
Creating Custom Roles

Build specialized roles for unique team responsibilities:
1

Navigate to Project Team Settings

Go to Project → Settings → Team → Roles tab
2

Click Add Role

Click the Add Role button in the top right
3

Name Your Role

Enter a descriptive name like “QA Reviewer” or “Knowledge Editor”
4

Add Description

Explain the role’s purpose so other admins understand when to use it
5

Select Permissions

Choose specific permissions grouped by functional area (Knowledge, Guidance, Conversations, etc.)
6

Save Role

Click Create Role to save
7

Assign to Team Members

Return to Members tab and assign the new role to appropriate team members
Common custom role examples: QA Reviewer
  • Purpose: Review conversations and apply labels without editing knowledge or deployments
  • Permissions: conversation:read, conversation:write, label:read, label:upsert, metric:read, topic:read
Knowledge Editor
  • Purpose: Maintain knowledge base without deployment or integration access
  • Permissions: knowledge:read, knowledge:write, conversation:read, table:read, table:write, file:read
Analyst
  • Purpose: View analytics and export data for reporting without configuration access
  • Permissions: metric:read, topic:read, conversation:read, userpool:read, export:read, label:read
Integration Specialist
  • Purpose: Configure integrations without touching knowledge or guidance
  • Permissions: All integration permissions (zendesk:, salesforce:, slack:*), deployment:read, conversation:read

​
Editing Custom Roles

Modify existing custom roles as your team’s needs evolve:
  1. Navigate to Project → Settings → Team → Roles tab
  2. Find the custom role in the roles table
  3. Click the edit icon in the Actions column
  4. Modify name, description, or permissions
  5. Click Update Role
Effect on existing users:
  • All team members with this role immediately receive updated permissions
  • No need to reassign roles to individual users
  • Changes take effect in real-time
Organization role warnings during role updates: When you reduce permissions on a custom role, botBrains checks if any users with this role have organization roles that grant broader access. If conflicts exist, you’ll see a warning listing affected users and recommending organization role demotions.

​
Deleting Custom Roles

Remove custom roles you no longer need:
  1. Navigate to Project → Settings → Team → Roles tab
  2. Find the custom role
  3. Click the trash icon in Actions column
  4. Confirm deletion
What happens to members with deleted roles:
  • Users assigned the deleted role lose access to project
  • Users must be reassigned a different role to regain access
  • Built-in roles cannot be deleted
Before deleting:
  1. Check how many users have this role
  2. Assign them a different role first
  3. Then delete the unused custom role

​
Team Collaboration Patterns

​
Small Team (2-5 people)

Setup:
  • Assign Organization Member to everyone
  • Give Project Admin to team leads
  • Give Project Member to other contributors
  • Use built-in roles only
Why it works: Simple role structure with minimal overhead. Everyone can contribute without complex permission management.

​
Department-Based Teams

Setup:
  • Create separate projects for each department (Support Bot, Marketing Bot, Sales Bot)
  • Assign Organization Member to all employees
  • Give Project Owner to department leads
  • Give Project Member to department team members
  • Executives get Project Viewer across all projects
Why it works: Clear separation of responsibilities. Marketing team can’t accidentally break Support Bot. Executives maintain visibility without configuration access.

​
Development, Staging, Production

Setup:
  • Create three projects (Dev, Staging, Prod)
  • Developers get Project Admin in Dev, Project Member in Staging, Project Viewer in Prod
  • QA team gets Project Admin in Staging, Project Viewer in Dev and Prod
  • Support team gets Project Viewer in all three
  • Senior engineers get Project Admin in all three
Why it works: Prevents accidental production changes while enabling testing and development. Clear promotion path from dev to staging to production.

​
External Consultants

Setup:
  • Create custom “Consultant” role with limited read access
  • Assign Organization Member role
  • Grant Consultant role to specific projects
  • Remove export and API key permissions
Why it works: Consultants can review and provide recommendations without accessing sensitive data or making unauthorized changes.

​
Multi-Brand Organizations

Setup:
  • Create separate projects for each brand
  • Assign Organization Member to all team members
  • Create brand-specific teams with Project Owner per brand
  • Share data analysts across brands with Project Viewer
  • Organization Owners have visibility across all brands
Why it works: Complete data isolation between brands. Brand managers control their AI without affecting other brands. Analytics team can compare performance.

​
Monitoring and Auditing

​
Track Team Changes

botBrains maintains audit logs of team management actions: What’s logged:
  • New member invitations (who sent, to whom, with which role)
  • Invitation acceptances and revocations
  • Role changes (who changed, for whom, from what to what)
  • Member removals (who removed, whom, when)
  • Custom role creation and modification
Access audit logs: Available through organization and project settings for compliance and security monitoring.

​
Regular Team Audits

Conduct quarterly team access reviews:
1

Export Current Members

Document all team members and their current organization and project roles
2

Verify Continued Need

Confirm each person still needs their current access level based on current job responsibilities
3

Remove Departed Members

Remove accounts for people who left the organization (if not already done)
4

Update Changed Roles

Adjust access for people whose responsibilities changed
5

Review Custom Roles

Verify custom roles still match intended use cases and haven’t grown overly permissive
6

Document Findings

Record audit results and any changes made for compliance purposes

​
Security Best Practices

Limit Organization Owner assignments:
  • Only 1-2 trusted individuals should have Organization Owner
  • Never share Organization Owner credentials
  • Use strong passwords and enable 2FA
Remove access promptly:
  • Remove departing employees on their last day
  • During notice periods, consider downgrading to Project Viewer
  • Revoke API keys when team members leave
Use principle of least privilege:
  • Start everyone with Organization Member
  • Grant project-specific access based on actual needs
  • Use custom roles for specialized requirements
  • Regularly review and reduce unnecessary permissions
Separate development and production:
  • Different projects for different environments
  • More restrictive roles in production
  • Developers have full access in dev, limited access in prod
Monitor suspicious activity:
  • Review audit logs for unexpected role changes
  • Alert on Organization Owner role assignments
  • Track bulk permission grants

​
Troubleshooting

​
User Can’t See Invited Project

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 than invited - check email match
  4. Cache issue - have user sign out and back in
Solution:
  1. Navigate to Project → Settings → Team → Members
  2. Search for user by email
  3. If not found, check Invitations tab - may not have accepted
  4. If found with “No Project Role”, assign appropriate project role
  5. Have user refresh browser or sign out/in

​
Role Change Didn’t Restrict Access

Cause: User has permissive organization role that overrides project restrictions Solution:
  1. Navigate to Organization → Settings → Team
  2. Find the user
  3. Check their organization role
  4. If Organization Admin, change to Organization Member
  5. Return to project and verify project role restrictions now work

​
Can’t Remove Team Member

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 the removal
  • Organization Owner cannot be removed (inherent account owner)
  • If you need to remove yourself, have another admin do it

​
Invitation Expired

Cause: Invitations expire after a set period (shown in Invitations table) Solution:
  1. Navigate to Settings → Team → Invitations
  2. Find expired invitation
  3. Revoke expired invitation
  4. Send new invitation with same role

​
Wrong Role Assigned

Solution (before acceptance):
  1. Revoke existing invitation
  2. Send new invitation with correct role
Solution (after acceptance):
  1. Navigate to Settings → Team → Members
  2. Find the user
  3. Change to correct role using role dropdown

​
Next Steps

Now that you understand team management, explore related topics: