Widget Integration

This guide covers everything you need to integrate the Goldilocks chat widget into your website.

Basic Integration

Step 1: Get Your API Key

Log into Goldilocks
Go to Widget > Embed or Settings > Security
Copy your API key

Step 2: Add the Script

Add this code before the closing </body> tag:

<script
  src="https://widget.goldilocks.chat/embed.js"
  data-api-key="YOUR_API_KEY"
  async
></script>

Step 3: Verify

Visit your website. You should see the chat bubble (usually bottom-right).

Configuration Options

Data Attributes

Configure using HTML data attributes:

<script
  src="https://widget.goldilocks.chat/embed.js"
  data-api-key="YOUR_API_KEY"
  data-position="bottom-right"
  data-theme="light"
  data-auto-open="false"
  async
></script>

Attribute	Default	Options
`data-api-key`	Required	Your API key
`data-position`	`bottom-right`	`bottom-right`, `bottom-left`
`data-theme`	`light`	`light`, `dark`, `auto`
`data-auto-open`	`false`	`true`, `false`
`data-persona`	Default persona	Persona slug

JavaScript Configuration

For more control, use JavaScript:

<script>
  window.goldilocksSettings = {
    apiKey: 'YOUR_API_KEY',
    position: 'bottom-right',
    theme: 'light',
    autoOpen: false,
    persona: 'support-agent',
    
    // Customer identification
    customerId: 'customer-123',
    customerLabel: 'John Smith',
    
    // Custom context
    context: {
      currentPage: 'checkout',
      cartValue: 99.99
    }
  };
</script>
<script src="https://widget.goldilocks.chat/embed.js" async></script>

Platform-Specific Guides

WordPress

Option 1: Theme Editor

Go to Appearance > Theme Editor
Edit footer.php
Add embed code before </body>
Save

Option 2: Plugin

Install "Insert Headers and Footers" plugin
Go to Settings > Insert Headers and Footers
Add code to footer section
Save

Shopify

Go to Online Store > Themes
Click Actions > Edit Code
Open theme.liquid
Find </body> tag
Add embed code before it
Save

With Customer Data:

<script>
  window.goldilocksSettings = {
    apiKey: 'YOUR_API_KEY',
    customerId: '{{ customer.id | default: "" }}',
    customerLabel: '{{ customer.name | default: "" }}',
    context: {
      customer: {
        email: '{{ customer.email | default: "" }}',
        ordersCount: {{ customer.orders_count | default: 0 }},
        totalSpent: '{{ customer.total_spent | default: 0 }}'
      }
    }
  };
</script>
<script src="https://widget.goldilocks.chat/embed.js" async></script>

Wix

Go to Settings > Custom Code
Click Add Custom Code
Paste embed code
Set:
- Place code: Body - end
- Pages: All pages
Apply

Squarespace

Go to Settings > Advanced > Code Injection
Paste code in Footer section
Save

Webflow

Go to Project Settings > Custom Code
Paste in Footer Code section
Publish

Next.js

// app/layout.tsx or pages/_app.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://widget.goldilocks.chat/embed.js"
          data-api-key="YOUR_API_KEY"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

React

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    window.goldilocksSettings = {
      apiKey: 'YOUR_API_KEY',
      customerId: user?.id,
      customerLabel: user?.name
    };

    const script = document.createElement('script');
    script.src = 'https://widget.goldilocks.chat/embed.js';
    script.async = true;
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, [user]);

  return <div>Your app</div>;
}

Vue

<template>
  <div id="app">
    <!-- Your app -->
  </div>
</template>

<script>
export default {
  mounted() {
    window.goldilocksSettings = {
      apiKey: 'YOUR_API_KEY'
    };

    const script = document.createElement('script');
    script.src = 'https://widget.goldilocks.chat/embed.js';
    script.async = true;
    document.body.appendChild(script);
  }
};
</script>

Angular

// app.component.ts
import { Component, OnInit, Renderer2 } from '@angular/core';

@Component({
  selector: 'app-root',
  template: '<router-outlet></router-outlet>'
})
export class AppComponent implements OnInit {
  constructor(private renderer: Renderer2) {}

  ngOnInit() {
    (window as any).goldilocksSettings = {
      apiKey: 'YOUR_API_KEY'
    };

    const script = this.renderer.createElement('script');
    script.src = 'https://widget.goldilocks.chat/embed.js';
    script.async = true;
    this.renderer.appendChild(document.body, script);
  }
}

Conditional Loading

Load Only on Certain Pages

const supportPages = ['/help', '/support', '/faq'];
const currentPath = window.location.pathname;

if (supportPages.some(page => currentPath.startsWith(page))) {
  loadGoldilocks();
}

function loadGoldilocks() {
  const script = document.createElement('script');
  script.src = 'https://widget.goldilocks.chat/embed.js';
  script.dataset.apiKey = 'YOUR_API_KEY';
  document.body.appendChild(script);
}

Exclude Certain Pages

const excludedPages = ['/checkout', '/admin', '/login'];

if (!excludedPages.includes(window.location.pathname)) {
  loadGoldilocks();
}

Load After Delay

setTimeout(loadGoldilocks, 5000); // 5 second delay

Load on Scroll

window.addEventListener('scroll', function onScroll() {
  loadGoldilocks();
  window.removeEventListener('scroll', onScroll);
}, { once: true });

Troubleshooting

Check API key - Verify key is correct
Check domain restrictions - Is your domain allowed?
Check for errors - Open browser console
Check script loading - Network tab in dev tools
Check for conflicts - Other scripts blocking?

Adjust with CSS if needed:

.goldilocks-widget {
  /* Override position */
}

Or use the data-position attribute.

If widget is behind other elements:

window.goldilocksSettings = {
  apiKey: 'YOUR_API_KEY',
  zIndex: 999999
};

Script Blocked

If Content Security Policy blocks the script:

<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self' https://widget.goldilocks.chat;">

Performance

Async Loading

Always use async attribute:

<script src="..." async></script>

This prevents blocking page load.

Lazy Loading

For better performance, load after page is ready:

if (document.readyState === 'complete') {
  loadGoldilocks();
} else {
  window.addEventListener('load', loadGoldilocks);
}

The widget script is ~30KB gzipped and loads additional resources on demand.