Widget Options & API

This reference covers all configuration options and JavaScript methods available for the Goldilocks widget.

Configuration Options

Configure the widget using window.goldilocksSettings:

window.goldilocksSettings = {
  // Required
  apiKey: 'your-api-key',
  
  // Optional - see below for all options
};

Required Options

Option	Type	Description
`apiKey`	string	Your Goldilocks API key

Display Options

Option	Type	Default	Description
`position`	string	`'bottom-right'`	Widget position: `'bottom-right'`, `'bottom-left'`
`theme`	string	`'light'`	Color theme: `'light'`, `'dark'`, `'auto'`
`zIndex`	number	`999999`	CSS z-index for widget
`autoOpen`	boolean	`false`	Open widget automatically on load
`hideOnMobile`	boolean	`false`	Hide widget on mobile devices

Customer Options

Option	Type	Description
`customerId`	string	Unique identifier for the customer
`customerLabel`	string	Display name for the customer
`customerEmail`	string	Customer's email address
`customerData`	object	Additional customer attributes

Behavior Options

Option	Type	Default	Description
`persona`	string	Default	Persona slug to use
`greeting`	string	From config	Custom greeting message
`suggestedQuestions`	string[]	None	Suggested starter questions
`preFill`	string	None	Pre-fill chat input

Context Options

Option	Type	Description
`context`	object	Page/session context data
`metadata`	object	Custom metadata passed with messages

Full Configuration Example

window.goldilocksSettings = {
  // Required
  apiKey: 'gld_live_abc123',
  
  // Display
  position: 'bottom-right',
  theme: 'auto',
  zIndex: 999999,
  autoOpen: false,
  
  // Customer
  customerId: 'cust_12345',
  customerLabel: 'John Smith',
  customerEmail: 'john@example.com',
  customerData: {
    plan: 'pro',
    tenure: '2 years',
    totalPurchases: 5
  },
  
  // Behavior
  persona: 'support-agent',
  greeting: 'Hi! How can I help you today?',
  suggestedQuestions: [
    'How do I track my order?',
    'What is your return policy?'
  ],
  
  // Context
  context: {
    currentPage: '/products/widget-pro',
    cartValue: 149.99,
    itemsInCart: 3
  },
  
  // Callbacks (see below)
  onLoad: function() { console.log('Loaded'); }
};

JavaScript API

Once loaded, the widget exposes methods on window.Goldilocks.

// Open the widget
Goldilocks.open();

// Close the widget
Goldilocks.close();

// Toggle open/close
Goldilocks.toggle();

// Check if open
const isOpen = Goldilocks.isOpen(); // true/false

// Show widget (if hidden)
Goldilocks.show();

// Hide widget
Goldilocks.hide();

// Check visibility
const isVisible = Goldilocks.isVisible(); // true/false

Messaging

// Send a message as if user typed it
Goldilocks.sendMessage('I need help with my order');

// Send with metadata
Goldilocks.sendMessage('Help with order', {
  metadata: {
    orderId: '12345',
    urgent: true
  }
});

Context Updates

// Set context (replaces existing)
Goldilocks.setContext({
  currentPage: 'checkout',
  cartValue: 299.99
});

// Update context (merges with existing)
Goldilocks.updateContext({
  cartValue: 349.99  // Updates just this field
});

// Get current context
const context = Goldilocks.getContext();

Customer Updates

// Update customer info
Goldilocks.setCustomer({
  id: 'cust_12345',
  label: 'John Smith',
  email: 'john@example.com'
});

// Clear customer (anonymous)
Goldilocks.clearCustomer();

Conversation Management

// Start a new conversation
Goldilocks.newConversation();

// Get current conversation ID
const conversationId = Goldilocks.getConversationId();

Configuration

// Update settings
Goldilocks.configure({
  theme: 'dark',
  position: 'bottom-left'
});

// Change persona
Goldilocks.setPersona('sales-agent');

Event Callbacks

window.goldilocksSettings = {
  apiKey: 'your-key',
  
  // Widget loaded
  onLoad: function() {
    console.log('Widget ready');
  },
  
  // Widget opened
  onOpen: function() {
    analytics.track('Chat Opened');
  },
  
  // Widget closed
  onClose: function() {
    analytics.track('Chat Closed');
  },
  
  // User sent message
  onMessageSent: function(message) {
    console.log('User:', message);
  },
  
  // AI responded
  onMessageReceived: function(message) {
    console.log('AI:', message);
  },
  
  // Conversation started
  onConversationStart: function(conversationId) {
    console.log('New conversation:', conversationId);
  },
  
  // Escalation requested
  onEscalation: function(data) {
    console.log('Escalated:', data);
    // data.email, data.message, etc.
  },
  
  // Error occurred
  onError: function(error) {
    console.error('Widget error:', error);
  }
};

Event Listeners

Alternative to callback registration:

// After widget loads
window.addEventListener('goldilocks:load', function(e) {
  console.log('Widget loaded');
});

window.addEventListener('goldilocks:open', function(e) {
  console.log('Widget opened');
});

window.addEventListener('goldilocks:message', function(e) {
  console.log('Message:', e.detail);
});

// Check if widget is loaded
if (window.Goldilocks) {
  // Widget is ready
  Goldilocks.open();
} else {
  // Wait for load
  window.addEventListener('goldilocks:load', function() {
    Goldilocks.open();
  });
}

// Or use the onLoad callback
window.goldilocksSettings = {
  apiKey: 'your-key',
  onLoad: function() {
    // Widget ready
  }
};

TypeScript Support

Type definitions for TypeScript projects:

interface GoldilocksSettings {
  apiKey: string;
  position?: 'bottom-right' | 'bottom-left';
  theme?: 'light' | 'dark' | 'auto';
  zIndex?: number;
  autoOpen?: boolean;
  customerId?: string;
  customerLabel?: string;
  customerEmail?: string;
  customerData?: Record<string, any>;
  persona?: string;
  context?: Record<string, any>;
  onLoad?: () => void;
  onOpen?: () => void;
  onClose?: () => void;
  onMessageSent?: (message: string) => void;
  onMessageReceived?: (message: string) => void;
  onError?: (error: Error) => void;
}

interface Goldilocks {
  open(): void;
  close(): void;
  toggle(): void;
  isOpen(): boolean;
  show(): void;
  hide(): void;
  isVisible(): boolean;
  sendMessage(message: string, options?: object): void;
  setContext(context: object): void;
  updateContext(context: object): void;
  getContext(): object;
  setCustomer(customer: object): void;
  clearCustomer(): void;
  newConversation(): void;
  getConversationId(): string | null;
  configure(settings: Partial<GoldilocksSettings>): void;
  setPersona(persona: string): void;
}

declare global {
  interface Window {
    goldilocksSettings?: GoldilocksSettings;
    Goldilocks?: Goldilocks;
  }
}