Chat Options & API

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

Configuration Options

Configure the widget using gl_chat('init', config) or data attributes on the script tag. Pass a config object with these 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'`
`autoOpen`	boolean	`false`	Open widget automatically on load
`autoOpenDelay`	number	`3000`	Delay in ms before auto-opening (when `autoOpen` is true)
`primaryColor`	string	-	Override primary color (hex)
`botName`	string	-	Override bot name

Contact Options

Option	Type	Description
`customerId`	string	Unique identifier for the contact
`customerLabel`	string	Display name for the contact
`customerName`	string	Contact's full name
`customerEmail`	string	Contact's email address

Behavior Options

Option	Type	Description
`settings.personaId`	string	Persona public ID to use (e.g. `pers_abc123`)
`isTest`	boolean	Mark conversations as test (excluded from history and billing)

Custom Context

Pass custom key-value pairs in settings for page/session context. These are sent with each message:

gl_chat('init', {
  apiKey: 'your-key',
  settings: {
    personaId: 'pers_abc123',
    currentPage: '/checkout',
    cartValue: 99.99
  }
});

Or add custom fields via gl_chat('identify', { id: '...', plan: 'pro', ... }) - any extra keys become context.

Full Configuration Example

gl_chat('init', {
  apiKey: 'gld_live_abc123',
  position: 'bottom-right',
  theme: 'auto',
  autoOpen: false,
  customerId: 'cust_12345',
  customerLabel: 'John Smith',
  customerEmail: 'john@example.com',
  settings: {
    personaId: 'pers_abc123',
    currentPage: '/products/widget-pro',
    cartValue: 149.99,
    itemsInCart: 3
  }
});

JavaScript API (gl_chat)

The widget uses a queue-based API via gl_chat(). Commands work before or after the script loads.

Commands

Command	Description
`gl_chat('init', config)`	Initialize with API key and options
`gl_chat('identify', { id, name, email, ... })`	Set contact and context data
`gl_chat('open')`	Open the widget
`gl_chat('close')`	Close the widget
`gl_chat('toggle')`	Toggle open/closed
`gl_chat('send', message)`	Send a message (opens if closed)
`gl_chat('navigate', tab)`	Navigate to a tab
`gl_chat('on', callback)`	Register event callback

Navigate Tab Values

Valid values for gl_chat('navigate', tab):

home - Home view
messages - Chat view
help - Help tab
support - Support/contact tab

Examples

// Initialize (or use data-key on script tag)
gl_chat('init', { apiKey: 'your-key' });

// Identify contact
gl_chat('identify', {
  id: 'cust_12345',
  name: 'John Smith',
  email: 'john@example.com',
  plan: 'pro'
});

// Control
gl_chat('open');
gl_chat('close');
gl_chat('toggle');
gl_chat('send', 'I need help with my order');

// Navigate
gl_chat('navigate', 'support');

The widget also exposes window.GoldilocksV2 and gl_chat.instance for direct access. The gl_chat queue API is the recommended interface.

Event Handling

Subscribe to widget events using gl_chat('on', handler). The handler receives event objects with a type and optional payload:

gl_chat('on', function(event) {
  switch (event.type) {
    case 'open':
      console.log('Widget opened');
      break;
    case 'close':
      console.log('Widget closed');
      break;
    case 'message_sent':
      console.log('User sent:', event.message);
      break;
    case 'message_received':
      console.log('AI replied:', event.message);
      break;
    case 'escalation_requested':
      console.log('Escalation requested');
      break;
    case 'resolution_yes':
      console.log('User marked resolved');
      break;
    case 'resolution_no':
      console.log('User marked not resolved');
      break;
    case 'error':
      console.error('Widget error:', event.error);
      break;
  }
});

Event Types

Event	Payload	Description
`open`	-	Widget was opened
`close`	-	Widget was closed
`message_sent`	`{ message }`	User sent a message
`message_received`	`{ message }`	AI responded
`escalation_requested`	-	User requested human support
`resolution_yes`	-	User confirmed resolution
`resolution_no`	-	User said not resolved
`error`	`{ error }`	An error occurred

Call gl_chat('on', handler) after the widget has loaded and initialized. If called before the script loads, the handler may not be registered (the queue is processed before auto-init). Use a load or DOMContentLoaded listener to ensure the widget is ready.

// Check if widget is loaded and get direct access
if (gl_chat.instance) {
  gl_chat.instance.open();
  gl_chat.instance.close();
} else {
  // Queue commands - they run when widget loads
  gl_chat('open');
}

// Or use window.GoldilocksV2 (constructor) / gl_chat.instance (instance)
if (window.gl_chat?.instance) {
  window.gl_chat.instance.toggle();
}

TypeScript Support

Type definitions for TypeScript projects:

interface WidgetConfig {
  apiKey: string;
  position?: 'bottom-right' | 'bottom-left';
  theme?: 'light' | 'dark' | 'auto';
  autoOpen?: boolean;
  autoOpenDelay?: number;
  primaryColor?: string;
  botName?: string;
  customerId?: string;
  customerLabel?: string;
  customerName?: string;
  customerEmail?: string;
  isTest?: boolean;
  serviceDomain?: string;
  settings?: Record<string, unknown>;
}

interface IdentifyData {
  id?: string;
  name?: string;
  email?: string;
  [key: string]: unknown;
}

type WidgetEvent =
  | { type: 'open' }
  | { type: 'close' }
  | { type: 'message_sent'; message: string }
  | { type: 'message_received'; message: string }
  | { type: 'escalation_requested' }
  | { type: 'resolution_yes' }
  | { type: 'resolution_no' }
  | { type: 'error'; error: string };

interface GoldilocksV2 {
  open(): void;
  close(): void;
  toggle(): void;
  openAndSend(message: string): void;
  navigateTo(view: 'home' | 'messages' | 'help' | 'support'): void;
  identify(data: IdentifyData): void;
  on(handler: (event: WidgetEvent) => void): () => void;
}

declare global {
  interface Window {
    gl_chat: ((cmd: string, ...args: unknown[]) => void) & { instance?: GoldilocksV2 };
    GoldilocksV2: new () => GoldilocksV2;
  }
}