Skip to main content

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 Overview

The Navi widget accepts a configuration object with required and optional parameters. Here’s the complete structure: 
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 for more examples
// 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 for details

​
enableConversationRestore

  • Type: boolean
  • Default: false
  • Description: Enable conversation persistence across page refreshes for voice
  • Note: See 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)
// 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"
// 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
// 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
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
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

// 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
defaultLanguage: {
  voice: string  // Language code (e.g., "en", "es", "fr")
}

​
Supported Languages

The widget supports 32 languages via ElevenLabs:
LanguageCodeLanguageCode
EnglishenPortuguesept
SpanishesRussianru
FrenchfrChinesezh
GermandeJapaneseja
ItalianitKoreanko
DutchnlArabicar
HindihiTurkishtr
PolishplSwedishsv
NorwegiannoDanishda
FinnishfiGreekel
CzechcsCroatianhr
RomanianroBulgarianbg
UkrainianukSlovaksk
HungarianhuVietnamesevi
IndonesianidMalayms
FilipinofilTamilta
// 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
onReady: () => {
  console.log("Widget ready");
  // Enable UI elements, track analytics, etc.
}

​
onError

  • Type: function(error)
  • Description: Called when an error occurs
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
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
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: 
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

// 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: 
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);
    }
  }
});