Advanced Widget Options

Beyond the settings available in the Widget page, these advanced options give you programmatic control over widget behavior and integration through JavaScript.

JavaScript API (gl_chat)

The widget exposes a queue-based API via gl_chat(). You can call it before or after the script loads - commands are queued until the widget initializes.

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

Control Commands

// Open widget
gl_chat('open');

// Close widget
gl_chat('close');

// Toggle open/closed
gl_chat('toggle');

Messaging

// Send a message (opens widget and sends)
gl_chat('send', 'I need help with my order');

Identity & Context

// Set contact info (call before or after init)
gl_chat('identify', {
  id: 'cust_123',
  name: 'John Smith',
  email: 'john@example.com',
  plan: 'pro'  // custom fields
});

// Initialize with config (if not using data attributes)
gl_chat('init', { apiKey: 'your-key', customerId: 'cust_123' });

// Navigate to a specific tab: 'home', 'messages', 'help', or 'support'
gl_chat('navigate', 'support');

Programmatic Control (Legacy)

For compatibility, window.GoldilocksV2 provides direct methods. Prefer gl_chat() for new integrations.

Opening/Closing

// Open widget
gl_chat('open');

// Close widget
gl_chat('close');

// Toggle
gl_chat('toggle');

Send Messages

// Send message as if user typed it
gl_chat('send', 'I need help with my order');

Event Callbacks

Subscribe to widget events with gl_chat('on', handler). Call this after the widget has loaded:

gl_chat('on', function(event) {
  switch (event.type) {
    case 'open':
      console.log('Widget opened');
      gtag('event', '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 responded:', event.message);
      break;
    case 'escalation_requested':
      console.log('Escalation requested');
      break;
    case 'resolution_yes':
    case 'resolution_no':
      console.log('Resolution feedback');
      break;
    case 'error':
      console.error('Widget error:', event.error);
      break;
  }
});

Custom Context Data

Pass page-specific context via gl_chat('identify', {...}) or in settings when calling init:

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

Dynamic Context

Update context as users navigate:

gl_chat('identify', {
  id: 'cust_123',
  currentPage: 'product-detail',
  productId: 'SKU-123',
  productName: 'Widget Pro'
});

Persona Selection

Specify which persona to use:

gl_chat('init', {
  apiKey: 'your-api-key',
  settings: { personaId: 'pers_sales123' }
});

Or use the data-persona attribute on the script tag:

<script src="https://api.goldilocks.chat/goldilocks.js" data-key="your-api-key" data-persona="pers_sales123" async></script>

Dynamic Persona

Change persona by calling init before the script loads:

if (window.location.pathname.includes('/pricing')) {
  gl_chat('init', { apiKey: 'your-api-key', settings: { personaId: 'pers_sales' } });
} else {
  gl_chat('init', { apiKey: 'your-api-key', settings: { personaId: 'pers_support' } });
}

Conditional Loading

Only load widget on certain pages:

// Only on support pages
if (window.location.pathname.startsWith('/support')) {
  loadGoldilocksWidget();
}

function loadGoldilocksWidget() {
  const script = document.createElement('script');
  script.src = 'https://api.goldilocks.chat/goldilocks.js';
  script.setAttribute('data-key', 'your-api-key');
  script.async = true;
  document.body.appendChild(script);
}

Exclude Pages

const excludedPaths = ['/checkout', '/login', '/admin'];
const currentPath = window.location.pathname;

if (!excludedPaths.some(path => currentPath.startsWith(path))) {
  loadGoldilocksWidget();
}

Delayed Loading

Load widget after page is ready:

// After DOM ready
document.addEventListener('DOMContentLoaded', function() {
  setTimeout(loadGoldilocksWidget, 3000); // 3 second delay
});

// After user scrolls
window.addEventListener('scroll', function onScroll() {
  loadGoldilocksWidget();
  window.removeEventListener('scroll', onScroll);
}, { once: true });

Custom Styling and Z-Index

Override widget stacking with CSS:

/* Widget container - adjust selector if needed */
[data-goldilocks-widget] {
  z-index: 999999 !important;
}

Additional Custom Styling

Override default styles:

/* Widget button */
.goldilocks-launcher {
  background-color: #your-color !important;
}

/* Chat container */
.goldilocks-container {
  border-radius: 16px !important;
  box-shadow: 0 10px 40px rgba(0,0,0,0.2) !important;
}

/* Messages */
.goldilocks-message.ai {
  background-color: #f0f0f0 !important;
}

Custom CSS may break with widget updates. Use sparingly and test after updates.

Single Page Applications

For SPAs (React, Vue, Angular):

React Example

import { useEffect, useCallback } from 'react';
import { useLocation } from 'react-router-dom';

function useGoldilocks() {
  const location = useLocation();

  useEffect(() => {
    // Update context on route change
    gl_chat('identify', { currentPage: location.pathname });
  }, [location]);

  const openWidget = useCallback(() => {
    gl_chat('open');
  }, []);

  return { openWidget };
}

Vue Example

// Plugin
export default {
  install(app) {
    app.config.globalProperties.$goldilocks = {
      open: () => gl_chat('open'),
      close: () => gl_chat('close'),
      identify: (ctx) => gl_chat('identify', ctx)
    };
  }
};

Analytics Integration

Google Analytics

gl_chat('on', function(event) {
  if (event.type === 'open') {
    gtag('event', 'widget_open', { event_category: 'support', event_label: 'goldilocks' });
  }
  if (event.type === 'message_sent') {
    gtag('event', 'chat_message', { event_category: 'support', event_label: 'user_message' });
  }
});

Segment

gl_chat('on', function(event) {
  if (event.type === 'open') analytics.track('Chat Widget Opened');
  if (event.type === 'message_sent') analytics.track('Chat Message Sent', { message: event.message });
  if (event.type === 'escalation_requested') analytics.track('Chat Escalated');
});

Accessibility

The widget supports keyboard navigation:

Tab to navigate elements
Enter to activate
Escape to close

Screen Readers

The widget is screen-reader compatible:

ARIA labels included
Focus management
Announcements for new messages

Troubleshooting

// Check if loaded (gl_chat.queue processes when script loads)
if (window.gl_chat?.instance) {
  console.log('Widget loaded');
} else {
  console.log('Widget not yet loaded - commands will queue');
}

// Commands can be called before script loads - they queue automatically
gl_chat('init', { apiKey: 'your-key' });
gl_chat('open');

Conflicts

If widget conflicts with other scripts:

Load widget last
Use async or defer
Check for namespace conflicts
Isolate with iframe (advanced)