User Tracking & Usage

​

user_identifier

• Type: string
• Description: Unique identifier for the user
• Note: Must be a string. Convert numeric IDs using String(userId)

// With user tracking
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: String(currentUser.id), // Convert to string
  company: "Acme Corporation" // Optional: Company name for tracking
});

​

company

• Type: string (optional)
• Description: Company name for user tracking, analytics, and filtering
• Usage: Used for user segmentation and analytics in the dashboard
• Benefits:
  • Filter conversations by company in the dashboard
  • Analyze usage patterns by organization
  • Generate company-specific reports and statistics

// With company tracking
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: "user-123",
  company: "Enterprise Solutions Inc" // Track by company
});

// Dynamic company assignment
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: String(currentUser.id),
  company: currentUser.organization // Use from user data
});

​

enableUsageChecking

• Type: boolean
• Default: true when user_identifier is provided
• Description: Control usage limit checking before widget initialization

• Checks user’s usage against configured monthly limits
• Silently blocks widget if limits exceeded
• Falls back to allowing access if check fails

// Disable usage checking (not recommended for production)
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: "user123",
  company: "Development Team", // Track by company
  enableUsageChecking: false
});

​

How Usage Checking Works

• Pre-initialization Check: Before the widget appears, the SDK checks the user’s current usage against configured limits
• Silent Blocking: If limits are exceeded, the widget doesn’t initialize (no error shown to end user)
• Error Callback: The onError callback receives details about usage limit violations
• Fail-Safe Behavior: If the usage check API fails, the widget initializes normally (conservative approach)

​

Configurable Limits

• Chat Conversations: Maximum number of chat sessions per month
• Voice Conversations: Maximum number of voice sessions per month
• Total Minutes: Maximum duration across all conversations per month

​

Example with Error Handling

initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: String(currentUserId),
  company: "Beta Testing Corp", // Track by company
  onError: (error) => {
    if (error.includes("Widget access denied")) {
      console.log("User has reached their usage limit");
      // Optionally show a custom message to the user
      showCustomLimitMessage();
    }
  }
});