Configuration Reference

initUnifiedWidget({
  // Required
  agentConfigId: string,
  agentKey: string,
  
  // Optional - Features
  chatEnabled: boolean,
  voiceEnabled: boolean,
  autoStart: boolean,
  enableConversationRestore: boolean,
  enableMemoryContext: boolean,
  
  // Optional - User & Usage
  user_identifier: 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,
});

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

// With user tracking
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  user_identifier: String(currentUser.id) // Convert to string
});

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

panelConfig: {
  title: string,       // Title in expanded panel
  description: string, // Description text
  expanded: boolean    // Start with panel expanded
}

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

// E-commerce Assistant
initUnifiedWidget({
  agentConfigId: "your-agent-id",
  agentKey: "your-agent-key",
  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",
  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
  }
});

defaultLanguage: {
  voice: string  // Language code (e.g., "en", "es", "fr")
}

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

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

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

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

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

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

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