> ## 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.

# Configuration Reference

> Complete reference for all Navi widget configuration options

## Configuration Overview

The Navi widget accepts a configuration object with required and optional parameters. Here's the complete structure:

```javascript theme={null}
initUnifiedWidget({
  // Required
  agentConfigId: string,
  agentKey: string,
  
  // Optional - Features
  chatEnabled: boolean,
  voiceEnabled: boolean,
  autoStart: boolean,
  enableConversationRestore: boolean,
  enableMemoryContext: boolean,
  
  // Optional - User & Usage
  user_identifier: string,
  company: string,
  enableUsageChecking: boolean,
  
  // Optional - Appearance
  name: string,
  panelConfig: object,
  position: object,
  
  // Optional - Language
  defaultLanguage: object,
  
  // Optional - Callbacks
  onReady: function,
  onError: function,
  onCallEnded: function,
  runTool: function,
});
```

## Required Parameters

### agentConfigId

* **Type**: `string`
* **Description**: Your Navi agent configuration ID from the dashboard
* **Example**: `"agent_abc123"`

### agentKey

* **Type**: `string`
* **Description**: Authentication key for SDK access (minimum 10 characters)
* **Example**: `"sk_live_abc123def456"`
* **Note**: This key only provides access to SDK endpoints, following the principle of least privilege

## Feature Configuration

### chatEnabled

* **Type**: `boolean`
* **Default**: `true`
* **Description**: Enable or disable chat functionality

### voiceEnabled

* **Type**: `boolean`
* **Default**: `true`
* **Description**: Enable or disable voice functionality

### autoStart

* **Type**: `boolean`
* **Default**: `false`
* **Description**: Automatically start a voice conversation when the widget loads
* **Requirements**: `voiceEnabled` must be `true`
* **Note**: Starts voice mode after a 2-second delay once the agent config is loaded
* **See**: [Feature Configuration](/integration/feature-configuration#autostart) for more examples

```javascript theme={null}
// Auto-start voice conversation
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  autoStart: true,
  voiceEnabled: true // Required for autoStart to work
});
```

### enableMemoryContext

* **Type**: `boolean`
* **Default**: `true`
* **Description**: Enable intelligent conversation continuity for onboarding agents
* **Note**: See [Feature Configuration](/integration/feature-configuration) for details

### enableConversationRestore

* **Type**: `boolean`
* **Default**: `false`
* **Description**: Enable conversation persistence across page refreshes for voice
* **Note**: See [Feature Configuration](/integration/feature-configuration) for details

## User Identification & Usage

### 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`
* **Description**: Company name for user tracking, analytics, and filtering
* **Usage**: Used for user segmentation and analytics in the dashboard
* **Example**: `"Acme Corporation"`, `"Tech Startup Inc"`

```javascript theme={null}
// With company tracking
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: "user123",
  company: "Enterprise Solutions Ltd" // Track by company
});
```

### 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
});
```

## Appearance & Customization

### name

* **Type**: `string`
* **Description**: Custom name shown in the widget header
* **Example**: `"Shop Assistant"`, `"Support Bot"`, `"Tour Guide"`

### panelConfig

* **Type**: `object`
* **Description**: Configure the expanded panel appearance

```javascript theme={null}
panelConfig: {
  title: string,       // Title in expanded panel
  description: string, // Description text
  expanded: boolean    // Start with panel expanded
}
```

### position

* **Type**: `object`
* **Description**: Configure widget positioning on the page

```javascript theme={null}
position: {
  alignment: string,  // Position preset
  margin: number,     // Distance from edges (px)
  offsetX: number,    // Horizontal offset (px)
  offsetY: number     // Vertical offset (px)
}
```

**Available alignments:**

* Top: `"top-left"`, `"top-center"`, `"top-right"`
* Middle: `"center-left"`, `"center"`, `"center-right"`
* Bottom: `"bottom-left"`, `"bottom-center"`, `"bottom-right"`

### Customization Examples

```javascript theme={null}
// E-commerce Assistant
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: "customer-123",
  company: "ShopMart Inc", // Track by company
  name: "Shop Assistant",
  panelConfig: {
    title: "Need Help Shopping?",
    description: "I can help you find products, compare prices, and guide you through checkout.",
    expanded: false
  },
  position: {
    alignment: "bottom-right",
    margin: 40
  }
});

// Customer Support
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: "user-456",
  company: "Support Solutions LLC", // Track support interactions
  name: "Support Bot",
  panelConfig: {
    title: "How Can We Help?",
    description: "I'm here to help with any questions about your account or orders.",
    expanded: true // Start open
  }
});
```

## Language Configuration

### defaultLanguage

* **Type**: `object`
* **Description**: Configure default language for voice interactions

```javascript theme={null}
defaultLanguage: {
  voice: string  // Language code (e.g., "en", "es", "fr")
}
```

### Supported Languages

The widget supports 32 languages via ElevenLabs:

| Language   | Code  | Language   | Code |
| ---------- | ----- | ---------- | ---- |
| English    | `en`  | Portuguese | `pt` |
| Spanish    | `es`  | Russian    | `ru` |
| French     | `fr`  | Chinese    | `zh` |
| German     | `de`  | Japanese   | `ja` |
| Italian    | `it`  | Korean     | `ko` |
| Dutch      | `nl`  | Arabic     | `ar` |
| Hindi      | `hi`  | Turkish    | `tr` |
| Polish     | `pl`  | Swedish    | `sv` |
| Norwegian  | `no`  | Danish     | `da` |
| Finnish    | `fi`  | Greek      | `el` |
| Czech      | `cs`  | Croatian   | `hr` |
| Romanian   | `ro`  | Bulgarian  | `bg` |
| Ukrainian  | `uk`  | Slovak     | `sk` |
| Hungarian  | `hu`  | Vietnamese | `vi` |
| Indonesian | `id`  | Malay      | `ms` |
| Filipino   | `fil` | Tamil      | `ta` |

```javascript theme={null}
// Spanish configuration
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  defaultLanguage: {
    voice: "es"
  }
});

// With i18n framework
const userLocale = i18n.language; // "fr", "de", etc.
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  defaultLanguage: {
    voice: userLocale
  }
});
```

## Event Handlers

### onReady

* **Type**: `function`
* **Description**: Called when the widget is ready for interaction

```javascript theme={null}
onReady: () => {
  console.log("Widget ready");
  // Enable UI elements, track analytics, etc.
}
```

### onError

* **Type**: `function(error)`
* **Description**: Called when an error occurs

```javascript theme={null}
onError: (error) => {
  console.error("Widget error:", error);
  // Show user-friendly error message
  if (error.message.includes("microphone")) {
    showMicrophoneHelp();
  }
}
```

### onCallEnded

* **Type**: `function(summary)`
* **Description**: Called when a voice call or chat session ends

```javascript theme={null}
onCallEnded: (summary) => {
  console.log("Session ended:", summary);
  // Track analytics, show feedback form, etc.
  analytics.track("navi_session_ended", {
    duration: summary.duration,
    messageCount: summary.messages?.length
  });
}
```

### runTool

* **Type**: `function(toolName, args)`
* **Description**: Handle tool execution requests from the assistant

```javascript theme={null}
runTool: (toolName, args) => {
  switch (toolName) {
    case "navigate":
      // SPA navigation without page refresh
      router.push(args.url);
      break;
    case "show_info":
      // Display information
      showModal(args.message);
      break;
    case "update_cart":
      // Update shopping cart
      cart.update(args.items);
      break;
    default:
      console.log("Unknown tool:", toolName, args);
  }
}
```

## User Context API

Send contextual information to the assistant from anywhere in your application:

```javascript theme={null}
import { sendUserContext } from "navi-web";

// Silent context (background info)
sendUserContext("User viewing product #123, price: $299");

// User message (visible in chat)
sendUserContext("I need help with this order", { silent: false });
```

### Context Best Practices

```javascript theme={null}
// Page navigation
useEffect(() => {
  sendUserContext(`User navigated to ${location.pathname}`);
}, [location]);

// User actions
const handleAddToCart = (product) => {
  sendUserContext(`Added ${product.name} to cart, price: ${product.price}`);
  // ... cart logic
};

// Error context
try {
  await submitForm(data);
} catch (error) {
  sendUserContext(`Form submission failed: ${error.message}`);
}
```

## Complete Example

Here's a full configuration example with all common options:

```javascript theme={null}
import { initUnifiedWidget, sendUserContext } from "navi-web";

initUnifiedWidget({
  // Required
  agentConfigId: "agent_abc123",
  agentKey: "sk_live_xyz789abc",
  
  // User tracking
  user_identifier: String(currentUser.id),
  
  // Features
  chatEnabled: true,
  voiceEnabled: true,
  autoStart: false, // Set to true to auto-start voice conversation
  enableConversationRestore: true,
  
  // Appearance
  name: "Product Assistant",
  panelConfig: {
    title: "Welcome to Our Store",
    description: "I can help you find products, answer questions, and guide you through checkout.",
    expanded: false
  },
  position: {
    alignment: "bottom-right",
    margin: 40,
    offsetX: 0,
    offsetY: -60 // Avoid footer
  },
  
  // Language
  defaultLanguage: {
    voice: "en"
  },
  
  // Callbacks
  onReady: () => {
    console.log("Navi widget ready");
    sendUserContext(`User on ${window.location.pathname}`);
  },
  
  onError: (error) => {
    console.error("Navi error:", error);
  },
  
  onCallEnded: (summary) => {
    analytics.track("navi_session", summary);
  },
  
  runTool: (toolName, args) => {
    if (toolName === "navigate") {
      router.push(args.url);
    }
  }
});
```