> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynavi.guide/llms.txt
> Use this file to discover all available pages before exploring further.

# User Tracking & Usage

> Configure user identification and usage limit checking

## user\_identifier

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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

When enabled:

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

```javascript theme={null}
// 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

When usage checking is active:

* **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

The system can enforce limits on:

* **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

```javascript theme={null}
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();
    }
  }
});
```