Bubble Integration Guide

This guide shows you how to add Heyo to your Bubble application without writing any code.

Installation

Step 1: Create an HTML Element

1. In your Bubble editor, navigate to the page where you want to add the chat
2. Click the Visual Elements tab
3. Drag an HTML element onto your page
4. You can place it anywhere - it won't be visible, but the chat will still work

Step 2: Add Heyo Code

Paste this code into the HTML element:

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

Replace YOUR_PROJECT_ID with your actual Project ID from the Heyo dashboard.

Step 3: Make it Site-Wide (Optional)

To show the chat on all pages:

1. Create a Reusable Element (Element → New Reusable Element)
2. Name it something like "Heyo Chat Widget"
3. Add the HTML element with the Heyo code to this reusable element
4. Add the reusable element to each page's header or footer

Show Chat Only to Logged-In Users

Using Conditional Formatting

1. Select your HTML element containing the Heyo code
2. Click the Conditional tab
3. Add a condition: "When Current User is logged out"
4. Set "This element is visible" to unchecked

This will hide the chat widget when users are not logged in.

Pass User Data to Chat

Method 1: Using Bubble Workflows

Create an HTML element with dynamic content:

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
<script>
window.addEventListener('load', function() {
  if (window.HEYO && <Current User is logged in>) {
    window.HEYO.init({
      projectId: 'YOUR_PROJECT_ID',
      user: {
        name: '<Current User's name>',
        email: '<Current User's email>',
        id: '<Current User's unique id>'
      }
    });
  }
});
</script>

To insert dynamic data:

1. Click "Insert dynamic data" in the HTML code editor
2. Select the appropriate Bubble field (e.g., Current User's name)
3. Repeat for email and ID

Method 2: Using Custom States

If you store user data in custom states:

1. Set up custom states for user info
2. Reference them in your HTML element using dynamic data
3. Use "Insert dynamic data" to populate the user object

Advanced Usage

Show Chat on Specific Pages

Create page-specific HTML elements instead of using a reusable element. Add the Heyo code only to pages where you want chat to appear.

Different Widgets for Different User Types

1. Create multiple Heyo projects in your dashboard (e.g., one for free users, one for premium)
2. Use conditional formatting to show different HTML elements based on user type
3. Each HTML element uses a different data-project-id

Example setup:

• Element 1: Shows for free users with Project ID A
• Element 2: Shows for premium users with Project ID B

Custom Chat Button

Hide the default Heyo button and create your own:

HTML Element for Heyo (hidden):

<script src="https://heyo.so/embed/script" defer data-project-id="YOUR_PROJECT_ID"></script>
<style>
  #heyo-widget-button {
    display: none !important;
  }
</style>

Custom Button in Bubble:

1. Create a Button element with your custom design
2. Add a Workflow: "When Button is clicked"
3. Add action: "Run JavaScript" (requires plugin)
4. JavaScript code: window.HEYO?.show();

Note: This requires the "Toolbox" plugin or similar JavaScript runner plugin.

Track Page Views

Send context about what users are viewing:

<script>
window.addEventListener('load', function() {
  if (window.HEYO) {
    window.HEYO.trackEvent('viewing_page', {
      page: '<Current Page name>',
      url: window.location.href
    });
  }
});
</script>

Responsive Design

Heyo is automatically responsive. However, if you want to adjust positioning for mobile:

Add this CSS in an HTML element:

<style>
  @media (max-width: 768px) {
    #heyo-widget-button {
      bottom: 80px !important; /* Adjust as needed */
    }
  }
</style>

Best Practices

• Use a reusable element for site-wide chat
• Set conditional visibility based on user login status
• Pass user data for personalized support
• Test on both desktop and mobile responsive modes
• Keep the HTML element hidden (it doesn't need to be visible)

Troubleshooting

Chat widget not appearing

• Verify your Project ID is correct
• Check that the HTML element is not hidden by conditions
• Ensure the element is on the page (check element tree)
• Preview/deploy your app to see changes

Widget appearing multiple times

• Make sure you haven't added multiple HTML elements with the same code
• Check that reusable elements aren't duplicated

Dynamic data not working

• Ensure you're using "Insert dynamic data" not just typing field names
• Check that Current User fields are accessible
• Verify user is logged in when passing user data

Not working in preview mode

• Some features may only work after deployment
• Try using Bubble's "Live" version instead of "Development"

Bubble Plugins Compatibility

Heyo works alongside other Bubble plugins without conflicts. It's compatible with:

• Toolbox (for advanced JavaScript control)
• All authentication plugins
• Payment processors (Stripe, etc.)
• Analytics plugins

Next Steps

• Customize widget colors
• Set up visitor alerts
• Create quick replies