Logo
Docs

HTML Integration Guide

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

This guide shows you how to add Heyo to any HTML website. Perfect for static sites, landing pages, and simple projects.

Installation

Basic Setup

Add this script tag before the closing </head> tag in your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
  
  <!-- Add Heyo here -->
  <script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

That's it! The chat widget will now appear on your page.

Multiple Pages

For multi-page sites, add the script to each HTML file, or create a shared header file:

Option 1: Template Header

Create header.html:

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>

Then include it in each page (using server-side includes, PHP, or your templating system).

Option 2: JavaScript Include

Create heyo.js:

(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);
})();

Include in your HTML:

<script src="/js/heyo.js"></script>

Advanced Usage

Custom Trigger Button

Create a custom button to open the chat:

<button onclick="window.HEYO.show()">Chat with us</button>

<style>
  button {
    padding: 12px 24px;
    background: #6366f1;
    color: white;
    border: none;
    border-radius: 8px;
    cursor: pointer;
    font-size: 16px;
  }
  
  button:hover {
    background: #4f46e5;
  }
</style>

Hide Default Widget Button

If using a custom button:

<style>
  #heyo-widget-button {
    display: none !important;
  }
</style>

Pass User Data

If you have user information (from a form or localStorage):

<script>
window.addEventListener('load', function() {
  // Get user data from wherever you store it
  const userName = localStorage.getItem('userName');
  const userEmail = localStorage.getItem('userEmail');
  
  if (window.HEYO && userName && userEmail) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: userName,
        email: userEmail
      }
    });
  }
});
</script>

Show/Hide on Specific Pages

<script>
window.addEventListener('load', function() {
  const currentPage = window.location.pathname;
  
  // Hide on thank you page
  if (currentPage.includes('thank-you.html')) {
    window.HEYO?.hide();
  }
  
  // Only show on contact page
  if (currentPage.includes('contact.html')) {
    window.HEYO?.show();
  }
});
</script>

Form Integration

Capture form data and pass to chat:

<form id="contactForm">
  <input type="text" id="name" placeholder="Name" required>
  <input type="email" id="email" placeholder="Email" required>
  <button type="submit">Submit</button>
</form>

<script>
document.getElementById('contactForm').addEventListener('submit', function(e) {
  e.preventDefault();
  
  const name = document.getElementById('name').value;
  const email = document.getElementById('email').value;
  
  // Initialize Heyo with user data
  if (window.HEYO) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: { name, email }
    });
    
    // Open chat automatically
    window.HEYO.show();
  }
});
</script>

Sticky Chat Button

Create a custom sticky button:

<button id="chatButton" onclick="window.HEYO?.show()">
  💬 Need Help?
</button>

<style>
  #chatButton {
    position: fixed;
    bottom: 20px;
    right: 20px;
    padding: 12px 24px;
    background: #6366f1;
    color: white;
    border: none;
    border-radius: 50px;
    cursor: pointer;
    font-size: 16px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
    z-index: 9999;
  }
  
  #chatButton:hover {
    background: #4f46e5;
    transform: translateY(-2px);
  }
  
  /* Hide default Heyo button */
  #heyo-widget-button {
    display: none !important;
  }
</style>

Static Site Generators

With Jekyll

In your _includes/head.html:

<script src="https://heyo.so/embed/script" defer data-project-id="{{ site.heyo_project_id }}"></script>

In _config.yml:

heyo_project_id: YOUR_PROJECT_ID

With Hugo

In your layouts/partials/head.html:

<script src="https://heyo.so/embed/script" defer data-project-id="{{ .Site.Params.heyoProjectId }}"></script>

In config.toml:

[params]
  heyoProjectId = "YOUR_PROJECT_ID"

With 11ty

In your _includes/head.njk:

<script src="https://heyo.so/embed/script" defer data-project-id="{{ heyo.projectId }}"></script>

GitHub Pages

Heyo works perfectly with GitHub Pages:

  1. Add the script to your HTML files
  2. Commit and push to your repository
  3. The widget will appear on your published site

No server-side code needed!

Performance Optimization

Lazy Loading

Load Heyo only after page load:

<script>
window.addEventListener('load', 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);
});
</script>

Load on Scroll

Load when user scrolls:

<script>
let loaded = false;

function loadHeyo() {
  if (!loaded) {
    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);
    loaded = true;
  }
}

window.addEventListener('scroll', loadHeyo, { once: true });
// Also load after 5 seconds if no scroll
setTimeout(loadHeyo, 5000);
</script>

Responsive Design

Control widget appearance on mobile:

<style>
  @media (max-width: 768px) {
    #heyo-widget-button {
      bottom: 10px !important;
      right: 10px !important;
      width: 56px !important;
      height: 56px !important;
    }
  }
</style>

Best Practices

  • Add the script in <head> with defer attribute
  • Use semantic HTML for custom trigger buttons
  • Test on different browsers (Chrome, Firefox, Safari)
  • Ensure widget doesn't cover important content
  • Make custom buttons accessible with proper ARIA labels
  • Test on mobile devices

Troubleshooting

Widget not appearing

  • Check that your Project ID is correct
  • Ensure JavaScript is enabled in the browser
  • Check browser console for errors
  • Verify the script is loading (check Network tab)

Script not loading

  • Make sure you have internet connection
  • Check if browser is blocking third-party scripts
  • Verify the script URL is correct

Multiple widgets appearing

  • Ensure you've only added the script once
  • Check for duplicate code in your HTML

Widget not responsive

  • Add viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1.0">
  • Check custom CSS isn't interfering

Next Steps

Ghost Integration Guide

Add Heyo live chat to your Ghost publication. Perfect for memberships and subscriber engagement.

JavaScript Integration Guide

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