Docs

JavaScript Integration Guide

Add Heyo live chat to your JavaScript application. Works with vanilla JS, jQuery, and any library.

This guide shows you how to add Heyo to any JavaScript application, whether using vanilla JS, jQuery, or any library.

Installation

Method 1: HTML Script Tag

Add to your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My App</title>
  <script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
</head>
<body>
  <!-- Your app -->
</body>
</html>

Method 2: JavaScript SDK

Install via npm:

npm install @heyo.so/js

Then in your JavaScript:

// Use either import style
import HEYO from '@heyo.so/js'; // or: import { HEYO } from '@heyo.so/js'

// Initialize on page load
window.addEventListener('load', () => {
  HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
});

Method 3: Dynamic Loading

Load the script dynamically:

(function() {
  const script = document.createElement('script');
  script.src = 'https://heyo.so/embed/script';
  script.defer = true;
  script.setAttribute('data-project-id', 'YOUR_PROJECT_ID');
  document.head.appendChild(script);
})();

Programmatic Control

Show, Hide, Toggle

// Show the chat widget
window.HEYO.show();

// Hide the chat widget
window.HEYO.hide();

// Toggle visibility
window.HEYO.toggle();

Custom Trigger Button

<button id="chat-button">Need Help?</button>

<script>
document.getElementById('chat-button').addEventListener('click', () => {
  window.HEYO?.show();
});
</script>

Wait for Widget to Load

window.addEventListener('load', () => {
  if (window.HEYO) {
    // Widget is ready
    console.log('Heyo is loaded');
  }
});

Advanced Usage

Pass User Data

window.addEventListener('load', () => {
  const user = getUserFromSession(); // Your auth logic
  
  if (user) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: user.name,
        email: user.email,
        id: user.id
      }
    });
  }
});

Event Listeners

Track when chat opens/closes:

window.HEYO.onOpen(() => {
  console.log('Chat was opened');
  analytics.track('chat_opened');
});

window.HEYO.onClose(() => {
  console.log('Chat was closed');
  analytics.track('chat_closed');
});

Track widget ready state:

window.HEYO.onReady(() => {
  console.log('Heyo widget is fully loaded');
});

Track agent status changes:

window.HEYO.onAgentStatusChange((status) => {
  console.log('Agent status:', status); // 'online', 'away', or 'offline'
  
  if (status === 'online') {
    showNotification('Support is available!');
  }
});

Integration with Single-Page Apps

For SPAs that change routes without page reload:

// Call on route change
function onRouteChange(route) {
  // Show/hide chat based on route
  if (route === '/checkout') {
    window.HEYO?.hide();
  } else {
    window.HEYO?.show();
  }
}

// Your router integration
router.on('routeChange', onRouteChange);

With jQuery

$(document).ready(function() {
  // Initialize Heyo
  if (window.HEYO) {
    window.HEYO.init({ projectId: 'YOUR_PROJECT_ID' });
  }
  
  // Custom button
  $('#chat-trigger').on('click', function(e) {
    e.preventDefault();
    window.HEYO?.show();
  });
});

With Async/Await

async function initializeChat() {
  // Wait for user data
  const user = await fetchUserData();
  
  // Initialize with user context
  window.HEYO?.init({
    projectId: 'YOUR_PROJECT_ID',
    user: {
      name: user.name,
      email: user.email
    }
  });
}

window.addEventListener('load', initializeChat);

Module Pattern

const Chat = (function() {
  let initialized = false;
  
  function init(projectId, userData) {
    if (initialized) return;
    
    window.HEYO?.init({
      projectId,
      user: userData
    });
    
    initialized = true;
  }
  
  function open() {
    window.HEYO?.show();
  }
  
  function close() {
    window.HEYO?.hide();
  }
  
  return {
    init,
    open,
    close
  };
})();

// Usage
Chat.init('YOUR_PROJECT_ID', { name: 'John', email: '[email protected]' });
Chat.open();

ES6 Class

class HeyoChat {
  constructor(projectId) {
    this.projectId = projectId;
    this.init();
  }
  
  init() {
    window.addEventListener('load', () => {
      window.HEYO?.init({ projectId: this.projectId });
    });
  }
  
  show() {
    window.HEYO?.show();
  }
  
  hide() {
    window.HEYO?.hide();
  }
  
  setUser(user) {
    window.HEYO?.init({
      projectId: this.projectId,
      user
    });
  }
}

// Usage
const chat = new HeyoChat('YOUR_PROJECT_ID');
chat.show();

TypeScript Support

Add type definitions:

interface DynamicProjectSettings {
  widgetColor?: string;
  widgetStyle?: 'bubble' | 'agent-card';
  widgetPosition?: 'left' | 'right';
  widgetSize?: 'small' | 'medium' | 'large';
}

declare global {
  interface Window {
    HEYO: {
      _ready: boolean;
      show: (options?: { force?: boolean }) => void;
      hide: () => void;
      open: (options?: { force?: boolean }) => void;
      close: () => void;
      toggle: () => void;
      logout: () => void;
      isOpen: () => boolean;
      identify: (meta: Record<string, unknown>) => void;
      configure: (settings: Partial<DynamicProjectSettings>) => void;
      getAgentStatus: () => 'online' | 'away' | 'offline';
      onAgentStatusChange: (callback: (status: 'online' | 'away' | 'offline') => void) => void;
      onReady: (callback: () => void) => void;
      onOpen: (callback: () => void) => void;
      onClose: (callback: () => void) => void;
      addTag: (tag: string) => void;
      removeTag: (tag: string) => void;
      setTags: (tags: string[]) => void;
      setField: (key: string, value: string | number | boolean) => void;
      removeField: (key: string) => void;
    };
  }
}

export {};

Usage in TypeScript:

class ChatWidget {
  constructor() {
    this.setupEventListeners();
  }
  
  private setupEventListeners(): void {
    window.HEYO?.onReady(() => {
      console.log('Chat widget ready');
    });
    
    window.HEYO?.onOpen(() => {
      console.log('Chat opened');
    });
    
    window.HEYO?.onClose(() => {
      console.log('Chat closed');
    });
    
    window.HEYO?.onAgentStatusChange((status) => {
      this.handleStatusChange(status);
    });
  }
  
  private handleStatusChange(status: 'online' | 'away' | 'offline'): void {
    console.log('Agent status:', status);
  }
  
  public show(): void {
    window.HEYO?.show();
  }
  
  public hide(): void {
    window.HEYO?.hide();
  }
  
  public open(): void {
    window.HEYO?.open();
  }
  
  public close(): void {
    window.HEYO?.close();
  }
}

Best Practices

Load the script asynchronously (use defer attribute)
Wait for load event before calling HEYO methods
Use optional chaining (?.) when calling HEYO methods
Initialize once per page load
Handle cases where script fails to load gracefully
Pass user context for better support experience

Troubleshooting

HEYO is undefined

Ensure script has loaded before calling methods
Use window.addEventListener('load', ...)
Check for script loading errors in console

Methods not working

Verify Project ID is correct
Check browser console for errors
Ensure using correct method names

Multiple initializations

Only call init() once per page
Check you're not loading script multiple times

Next Steps

HTML Integration Guide

Add Heyo live chat to any HTML website. Simple copy-paste integration with no dependencies.

Laravel Integration Guide

Add Heyo live chat to your Laravel application with Blade template integration. Works with Livewire and Inertia.