On this page

Website Builders

Bubble Integration

Embed your Chatsby AI agent into your Bubble.io application. Covers HTML element method, dynamic bot IDs for multi-tenant apps, and troubleshooting.

Bubble Integration

Bubble is a powerful no-code platform for building web applications, and integrating a Chatsby AI agent into your Bubble app enables your users to get instant AI-powered support without leaving the application. Unlike traditional website builders, Bubble uses a visual element-based editor, so the integration process involves adding an HTML element rather than editing theme files. This guide covers the standard HTML element method, dynamic bot ID assignment for multi-tenant applications, testing in Bubble's preview mode, and detailed troubleshooting.

Prerequisites

RequirementDetails
Bubble accountAny Bubble plan (including the free plan for development and testing)
App editor accessYou need access to the Bubble app editor for the application you want to integrate with
Chatsby agentA trained agent set to Public with at least one data source
Embed scriptCopied from the Connect tab in your Chatsby dashboard

Bubble's free plan allows you to test the widget in preview mode. However, deploying to a live production URL requires a paid Bubble plan.

Standard Method: HTML Element

This is the recommended method for adding the Chatsby widget to your Bubble application. The HTML element acts as a container that executes your embed script when the page loads.

Open Your Bubble App Editor

Log in to your Bubble account and open the app where you want to add the Chatsby widget. Click Edit to open the visual editor.

Navigate to the Target Page

In the page navigator (top-left dropdown), select the page where you want the widget to appear. If you want the widget on every page, add it to your app's index page or a reusable element that is included on all pages.

Add an HTML Element

In the element palette on the left side, scroll down to the HTML element (sometimes listed under "Visual elements" or "Containers" depending on your Bubble version). Drag it onto the page canvas.

Configure the HTML Element

Click the HTML element to select it, then open its property editor. In the HTML content area (the "Appearance" tab), paste your Chatsby embed script:

<script
  src="https://chatsby.co/widget.min.js"
  bot-id="YOUR_BOT_ID"
  async
  defer
></script>

You can resize the HTML element to be very small (e.g., 1x1 pixel) and position it in a corner, since the Chatsby widget renders as a floating overlay and does not depend on the element's size or position.

Preview and Test

Click Preview in the top-right corner of the Bubble editor. The Chatsby chat bubble should appear in the bottom corner of the preview window. Click it and send a test message to verify the agent works correctly.

Deploy to Live

Once verified in preview, go to Deployment in the top menu and click Deploy to Live to push the changes to your production application.

Adding the Widget to All Pages Using a Reusable Element

If your Bubble app has multiple pages and you want the widget on every page, the most maintainable approach is to use a Reusable Element.

Create a Reusable Element

In the Bubble editor, go to the Reusable Elements tab. Click New reusable element and name it something like ChatWidget.

Add the HTML Element Inside It

Inside the reusable element editor, drag an HTML element onto the canvas and paste your Chatsby embed script into its content area (same as Step 4 above). Resize the reusable element and the HTML element to minimal dimensions (e.g., 10x10 pixels).

Include the Reusable Element on Each Page

Go to each page in your Bubble app and drag the ChatWidget reusable element onto it. Place it in any corner --- its visual size does not matter since the widget floats independently.

Dynamic Bot ID for Multi-Tenant Applications

If you are building a multi-tenant SaaS application on Bubble where each tenant (customer) has their own Chatsby agent, you can dynamically set the bot-id attribute based on the current user or tenant context.

Store Bot IDs in Your Database

In your Bubble database, add a field to your Tenant or Organization data type called chatsby_bot_id (type: text). Populate this field with the corresponding Chatsby agent ID for each tenant.

Use Dynamic Data in the HTML Element

In the HTML element's content area, use Bubble's dynamic data insertion to inject the bot ID:

<script
  src="https://chatsby.co/widget.min.js"
  bot-id="INSERT DYNAMIC DATA: Current User's Tenant's chatsby_bot_id"
  async
  defer
></script>

In the Bubble editor, click Insert dynamic data within the HTML content field and select the path to the current tenant's chatsby_bot_id field.

Test with Different Users

Preview the app as different test users to confirm that each tenant sees the correct Chatsby agent.

When using dynamic bot IDs, ensure that the chatsby_bot_id field has proper privacy rules set in your Bubble app. The bot ID itself is not sensitive (it is visible in the client-side script tag), but your data architecture should follow Bubble's privacy best practices.

Verifying the Installation

Use Bubble Preview Mode

Click Preview in the Bubble editor. This runs your app in a development environment where you can test the widget before deploying to production.

Confirm the Chat Bubble

The Chatsby chat bubble should appear as a floating icon in the bottom corner of the page.

Test a Conversation

Click the bubble and send a test message. Verify the agent responds correctly.

Deploy and Test on Live

After deploying to live, visit your production URL and repeat the test. Confirm the widget appears and works identically to the preview.

Troubleshooting

Widget Not Appearing in Preview

Possible CauseSolution
HTML element not visibleEnsure the HTML element is placed on the page canvas and is not hidden by a conditional visibility rule
Agent not PublicEnable the Public toggle on the Connect tab in the Chatsby dashboard
Browser blocking scriptsCheck the browser console (F12 > Console) for Content Security Policy errors or blocked script warnings
Bubble free plan restrictionsSome Bubble free plan limitations may affect script execution in preview. Try deploying to a live test version

Widget Appears in Preview but Not in Live

This usually means you have not deployed the latest version of your app to live. Go to Deployment > Deploy to Live and push the current development version.

Widget Conflicts with Bubble Elements

The Chatsby widget uses a high z-index to float above page content. If it overlaps with Bubble popups, floating groups, or fixed headers:

  • Adjust the widget position in the Settings > Chat Interface section of the Chatsby dashboard.
  • In Bubble, set the z-index of conflicting elements to a value below 9999 to ensure the widget remains accessible.

HTML Element Rendering Issues

If the HTML element shows the raw script text instead of executing it, ensure you are using Bubble's HTML element (which executes scripts) and not a Text element or Rich Text Editor element. Only the dedicated HTML element will execute embedded JavaScript.

Performance Considerations

The Chatsby widget loads asynchronously and does not impact your Bubble app's initial load time. However, if your Bubble app already has many workflows and plugins running on page load, the widget may take a moment longer to appear. This is normal and does not affect the user experience --- the widget simply renders once the script finishes loading.

Best Practices

  • Use a reusable element for the widget if it should appear on multiple pages. This ensures consistency and makes it easy to update the bot ID in a single location.
  • Train your agent on your app's documentation, FAQ, and onboarding content so it can help users navigate your Bubble application.
  • Use Chatsby Actions to capture user feedback, collect contact information, or trigger escalations without requiring users to leave the chat.
OverviewWebflow