Logo
Docs

Framer Integration Guide

Add Heyo live chat to your Framer website. Perfect for modern, interactive sites and agency projects.
Try Heyo for Framer →

This guide shows you how to add Heyo to your Framer website. Works with all Framer projects and templates.

Installation

Method 1: Using Custom Code Component (Recommended)

  1. In your Framer project, click the + button to add a new element
  2. Search for Custom Code component
  3. Drag it onto your page (or add it to a layout/component)
  4. In the code editor, select HTML and paste:
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
  1. Position the component anywhere (it won't be visible, but the chat will work)
  2. Publish your site

Method 2: Site-Wide Custom Code

For site-wide integration:

  1. Go to Settings (gear icon in top-left)
  2. Click General
  3. Scroll to Custom Code
  4. Add to the End of section:
<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
  1. Click Save and publish
The Custom Code feature is available on Framer's paid plans.

Advanced Integration

Custom Chat Button

Create a beautiful custom button in Framer to trigger the chat:

  1. Design your button in Framer
  2. Add a Code Component for the interaction:
import { useEffect } from "react"

export default function ChatButton() {
  const openChat = () => {
    if (window.HEYO) {
      window.HEYO.show()
    }
  }

  return (
    <button
      onClick={openChat}
      style={{
        padding: "12px 24px",
        background: "#6366f1",
        color: "white",
        border: "none",
        borderRadius: "8px",
        cursor: "pointer",
        fontSize: "16px",
      }}
    >
      Chat with us
    </button>
  )
}

Or use Framer's interactive capabilities:

<!-- Add to a Custom Code component -->
<script>
function openHeyoChat() {
  window.HEYO?.show();
}
</script>

<button onclick="openHeyoChat()" style="padding: 12px 24px; background: #6366f1; color: white; border: none; border-radius: 8px; cursor: pointer;">
  Need help?
</button>

Hide Default Widget

If using a custom trigger, hide the default Heyo button:

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

Route-Specific Display

Show/hide chat on specific pages:

// Code Component
import { useEffect } from "react"
import { useRouter } from "framer"

export default function HeyoControl() {
  const router = useRouter()
  
  useEffect(() => {
    // Hide on pricing page
    if (router.pathname === "/pricing") {
      window.HEYO?.hide()
    } else {
      window.HEYO?.show()
    }
  }, [router.pathname])
  
  return null
}

Framer CMS Integration

Pass CMS data to your chat widget:

// Code Component for CMS pages
export default function CMSHeyo({ title, author }) {
  useEffect(() => {
    if (window.HEYO) {
      window.HEYO.trackEvent("viewing_content", {
        title: title,
        author: author,
      })
    }
  }, [title, author])
  
  return null
}

Integration with Framer Motion

Heyo works seamlessly with Framer Motion animations. No conflicts!

Example of animating your custom chat button:

import { motion } from "framer-motion"

export default function AnimatedChatButton() {
  return (
    <motion.button
      onClick={() => window.HEYO?.show()}
      whileHover={{ scale: 1.05 }}
      whileTap={{ scale: 0.95 }}
      style={{
        padding: "12px 24px",
        background: "#6366f1",
        color: "white",
        border: "none",
        borderRadius: "8px",
        cursor: "pointer",
      }}
    >
      Chat with us
    </motion.button>
  )
}

Pass User Data

For authenticated Framer sites, pass user context:

// Code Component
import { useEffect } from "react"

export default function HeyoWithUser({ userName, userEmail }) {
  useEffect(() => {
    if (window.HEYO) {
      window.HEYO.init({
        projectId: "YOUR_PROJECT_ID",
        user: {
          name: userName,
          email: userEmail,
        },
      })
    }
  }, [userName, userEmail])
  
  return null
}

Responsive Behavior

Control widget visibility on different screen sizes:

<!-- Custom Code Component -->
<style>
  @media (max-width: 768px) {
    #heyo-widget-button {
      bottom: 20px;
      right: 20px;
    }
  }
</style>

Agency & Client Projects

Multi-Client Setup

For agencies:

  1. Create separate Heyo projects for each client
  2. Use different Project IDs in each Framer site
  3. Share inbox access with clients

Templates

If you're creating Framer templates:

  1. Add Heyo with a placeholder Project ID
  2. Document for users how to replace with their own ID
  3. Consider offering Heyo setup as a premium feature

Best Practices

  • Use custom code components for better control
  • Leverage Framer's component system for reusability
  • Test interactive states (hover, click) with custom buttons
  • Make sure chat button has good contrast on all backgrounds
  • Position widget to not interfere with Framer animations

Troubleshooting

Widget not showing

  • Verify you're on a paid Framer plan with Custom Code access
  • Check that Project ID is correct
  • Ensure custom code component is on published site
  • Clear browser cache

TypeScript errors in Code Components

Add type definitions:

declare global {
  interface Window {
    HEYO: {
      show: () => void
      hide: () => void
      toggle: () => void
      init: (config: any) => void
    }
  }
}

Conflicts with Framer interactions

  • Heyo shouldn't conflict with Framer interactions
  • If issues occur, adjust z-index in custom styles

Not persisting across pages

  • Make sure the Heyo script is in site-wide custom code
  • Or add the Custom Code component to your layout/master component

Next Steps

Flutter Integration Guide

Add Heyo live chat to your Flutter iOS and Android apps using WebView.

Ghost Integration Guide

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