Skip to main content

​
Users

Users in botBrains represent the people who interact with you AI agent. Whether they’re asking questions on your website, submitting support tickets, or messaging through integrated channels, botBrains tracks and organizes information about each unique person to provide personalized support and valuable customer insights.

​
Why User Management Matters

Effective user management transforms disconnected conversations into comprehensive customer profiles, enabling you to:

​
Build Complete Customer Profiles

Track all interactions from a single customer across channels and time. When someone reaches out via email today and chat tomorrow, botBrains recognizes them as the same person - giving you complete context for every conversation.

​
Deliver Personalized Support

Use customer information like language preferences, timezone, and conversation history to provide contextually relevant responses. Your AI can reference previous interactions, remember customer preferences, and adjust communication style based on user attributes.

​
Identify Support Patterns

Understand which customers need the most help, what types of questions they ask, and how effectively your AI serves different user segments. This insight helps you improve both automated and human support.

​
Segment and Target Users

Group customers by characteristics like location, behavior, or custom attributes to deliver targeted experiences. Send different guidance to enterprise customers versus free tier users, or adjust responses based on customer lifecycle stage.

​
How Users Are Tracked

botBrains automatically creates and manages user records as people interact with your AI. Here’s how the system identifies and organizes users:

​
User Identification

Users can be identified through multiple methods: Email Address - When provided, email serves as a primary identifier. botBrains tracks whether the email has been verified. Phone Number - Mobile or phone numbers can identify users, particularly in SMS or messaging integrations. The system tracks verification status. External ID - Your own unique identifier from CRM, authentication systems, or databases. This enables seamless integration with your existing user management. Anonymous Users - Users who haven’t provided identifying information are still tracked by device and session, allowing conversation history until they identify themselves.

​
User Attributes

botBrains automatically captures and maintains rich user information: 
{
  "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"
  }
}
Core Attributes:
  • Name - First and last name when provided
  • Contact Information - Email and phone with verification status
  • Timezone - Automatically detected from device or explicitly set
  • Languages - Preferred languages for communication
  • Last Seen - When the user last interacted with your AI
External Attributes: Pass custom data from your systems to enrich user profiles. Include subscription level, account status, purchase history, or any other relevant information. This data becomes available for personalization, segmentation, and analytics.

​
Verified Identities

botBrains tracks whether email addresses and phone numbers have been verified (signed). Verified identities indicate higher confidence that the user owns that contact method - useful for security-sensitive operations or understanding data quality.

​
User Pools

User pools organize users by environment or integration context. Most projects use a single user pool, but multiple pools enable important use cases:

​
Separate Development and Production

Maintain distinct user bases for testing and live environments. Test new features with development users without affecting production customer data.

​
Multi-Tenant Applications

If you serve multiple clients, create separate user pools for each client’s end users. This ensures complete data isolation and enables per-client analytics.

​
Geographic or Regulatory Separation

Organize users by region to comply with data residency requirements or manage different privacy regulations.

​
Managing Users

​
View User Profiles

Access detailed user information including:
  • Contact details and verification status
  • Language preferences and timezone
  • Custom attributes from your systems
  • Complete conversation history
  • Applied labels for organization
The user profile view provides a comprehensive timeline of all interactions, making it easy to understand the customer’s complete support journey.

​
Search and Filter Users

Find specific users or segments quickly using powerful search and filtering:
Search works across names, email addresses, phone numbers, and external IDs. Use the filters to narrow results by labels, identifiable status, or custom attributes.
Full-Text Search - Type any part of a name, email, or phone number to find matching users. The search indexes all identifiable information for fast retrieval. Filter by Labels - Find users tagged with specific labels like “vip-customer”, “enterprise-user”, or “needs-attention”. Combine multiple labels to create precise segments. Identifiable Users Only - Toggle to show only users who have provided identifying information (email, phone, or external ID). Useful for export compliance or targeted outreach.

​
Update User Information

Manually edit user profiles to correct information, add context, or enrich profiles with data from other systems. Updates immediately reflect across all views and future conversations.
Use the API to programmatically sync user data from your CRM, authentication system, or database. This ensures botBrains always has current customer information for personalization.

​
Label Users

Apply labels to organize users and enable targeted actions: 
vip-customer
enterprise-user
beta-tester
churned-customer
needs-followup
Labels appear in user profiles and enable filtering in analytics, exports, and audience targeting. Create labels that match your business processes and customer segmentation needs.

​
Working with User Conversations

Each user profile displays their complete conversation history, enabling:

​
View Past Interactions

See every conversation chronologically with full message content, timestamps, and AI responses. Understand what the customer has asked about and how issues were resolved.

​
Batch Operations

Select multiple conversations from a user to:
  • Mark as spam if the user is abusive
  • Hide conversations from analytics
  • Apply labels for organization
  • Export for analysis or compliance

​
Identify Patterns

Recognize recurring issues, frequent topics, or escalation triggers for specific users. Use this insight to proactively address problems or improve self-service content.

​
User Export

Export user data for analysis, compliance, or integration with other systems:
1

Apply Filters

Use search and filters to select the exact user segment you need
2

Choose Export

Click the Export button to create a data export request
3

Receive Download

Get notified when your export is ready and download the CSV or JSON file
Exports include all user attributes, contact information, and metadata. Use exports for:
  • GDPR compliance and data subject requests
  • CRM synchronization
  • Customer analytics in business intelligence tools
  • Bulk operations and data migration

​
Privacy and Security

botBrains handles user data with strong privacy and security controls: PII Protection - Personal information like email and external IDs are blurred in the UI by default, revealing on hover. This prevents accidental exposure in screenshots or screen shares. Access Control - Use role-based permissions to control who can view, edit, or export user data. Restrict sensitive operations to authorized team members. Data Retention - Configure retention policies to automatically remove user data after specified periods, supporting privacy regulations and data minimization principles. Audit Logs - Track all user data access, modifications, and exports for compliance and security monitoring.

​
Best Practices

​
Pass External IDs

Always include your system’s unique user identifier when initiating conversations. This enables seamless integration and ensures accurate user matching across platforms.

​
Enrich Profiles Progressively

Start with basic identification and add attributes over time as you learn more about customers. Use external attributes to store any relevant business data.

​
Use Verified Identities

Implement email or phone verification in your integration to increase data quality and enable confident personalization.

​
Label Strategically

Create a consistent labeling taxonomy that reflects your support processes. Use labels for triage, escalation triggers, and customer segmentation.

​
Monitor Identifiable Rate

Track what percentage of users provide identifying information. Low identification rates may indicate friction in your support flow or privacy concerns.

​
User Integration Patterns

​
Website Chat

Website Integration
botBrains.init({
  projectId: "your-project-id",
  user: {
    externalId: currentUser.id,
    email: currentUser.email,
    firstName: currentUser.firstName,
    lastName: currentUser.lastName,
    externalAttributes: {
      subscriptionTier: currentUser.plan,
      accountStatus: currentUser.status
    }
  }
});

​
Support Ticket Systems

When integrating with Zendesk, Salesforce, or other ticketing platforms, botBrains automatically extracts user information from ticket requesters and maintains synchronization between systems.

​
API-Based Integration

Use the botBrains API to create or update users programmatically, sync data from your CRM, or build custom user management workflows.

​
Next Steps

Now that you understand user management, explore related concepts: