> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an AI agent to your Bubble app

> Embed your Chatbase AI agent in a Bubble app using the website widget embed code

You can add your Chatbase AI agent to a Bubble.io app by pasting the Chatbase **Website widget** script into an **HTML** element on your page. Once the script loads, a floating Chat Bubble appears in the bottom corner of the app and opens the chat when users click it. The Chat Bubble is included on every Chatbase plan.

> [card] What you can do:
>
> Put your AI agent in front of every user of your Bubble app, answering questions without them leaving the page.

## Before you start

* A Chatbase account with an AI agent. If you haven't built one yet, follow [Your first AI agent](https://chatbase.co/docs/user-guides/quick-start/your-first-agent.md).
* A Bubble app you can edit.

## How to embed your AI agent

**1. Copy your embed code**

1. Log into your Chatbase account and navigate to your [dashboard](https://www.chatbase.co/dashboard/).
2. On the list of available AI agents, click the one you want to integrate into your Bubble app.
3. Click **Channels** in the left sidebar, then click **Manage** on the **Chat Bubble** card (or **Setup**, if you haven't configured it yet).
4. Click **Deploy** and select the **Website widget** embed type. Scroll down and click **Copy** to copy the provided script.

![The Deploy step showing the website widget embed code](https://mintcdn.com/chatbase/DnMdgLj-7YGWYAcx/user-guides/integrations/images/Integrations/deploy-step.png?fit=max\&auto=format\&n=DnMdgLj-7YGWYAcx\&q=85\&s=31b0448df7dee6c3ccc65eaf9bb47879)

**2. Open your Bubble app editor**

Sign into Bubble, go to your account dashboard, pick the app you want to embed the AI agent on, and click **Launch Editor**.

![Launching the editor for a Bubble app](https://mintcdn.com/chatbase/yfTgmAASFJyGs3D_/user-guides/integrations/images/bubble/bubble-4.png?fit=max\&auto=format\&n=yfTgmAASFJyGs3D_\&q=85\&s=5d7fa6ea82844111a6f5ac2268e99ec9)

**3. Add an HTML component**

Scroll to the section of the page where you want the AI agent. On the left sidebar of the editor, locate the **HTML** component and drag it onto the page.

![Dragging the HTML component onto a Bubble page](https://mintcdn.com/chatbase/yfTgmAASFJyGs3D_/user-guides/integrations/images/bubble/bubble-5.png?fit=max\&auto=format\&n=yfTgmAASFJyGs3D_\&q=85\&s=294e48a278f041d1b3707f3cbfbaceec)

**4. Paste the embed code**

Double-click the HTML component to reveal the code editor, then paste the embed code. You should automatically see a floating AI agent icon on the editing canvas.

![Pasting the embed code into the Bubble HTML component](https://mintcdn.com/chatbase/yfTgmAASFJyGs3D_/user-guides/integrations/images/bubble/bubble-6.png?fit=max\&auto=format\&n=yfTgmAASFJyGs3D_\&q=85\&s=4d360077b75fc3ef89bb54c93d8ba41a)

> [!TIP]
>
> Preview your Bubble app and confirm the Chat Bubble appears and your AI agent responds.

![The Chatbase Chat Bubble live in a Bubble app preview](https://mintcdn.com/chatbase/yfTgmAASFJyGs3D_/user-guides/integrations/images/bubble/bubble-7.png?fit=max\&auto=format\&n=yfTgmAASFJyGs3D_\&q=85\&s=eaa3de1123fb4ffbd8f689b5250fa4b4)

## Show the AI agent on every page of your app

The HTML element only loads the script on the page it sits on. To show the Chat Bubble on several pages, put the HTML element in a reusable element that appears on each of those pages, such as a shared header. Once the script has loaded, the Chat Bubble attaches to the page itself, not to the HTML element, so the element can be small and placed anywhere in the header.

## Allow your bubbleapps.io address

If you turned on **Only allow embedding the agent on specific domains** in the **Specific domains** card of the **Deploy** sheet, list each host your app runs on. For example (example values):

```text theme={null}
https://acme.bubbleapps.io
https://app.acme.com
```

Paths are ignored, so one `bubbleapps.io` entry covers both the development version (`/version-test`) and the live version of your app. A custom domain needs its own entry. An entry without `https://` or `http://` matches only https pages. See [Deploy button](https://chatbase.co/docs/user-guides/chatbot/channels.md#deploy-button).

## Troubleshooting

> [accordion] The Chat Bubble doesn't appear in preview or on the live app
>
> **Possible causes:**
>
> * **Specific domains** is on and your app's host isn't listed. The browser console shows a message starting with `[Chatbase] Agent` that says the agent is not allowed on that origin.
> * The visitor's country is in your [blocked countries](https://chatbase.co/docs/user-guides/chatbot/guardrails.md#blocking-a-country).
> * **Show to a percentage of visitors** is on under **Display > A/B testing**, and this visitor isn't in the sample.
>
> **Solution:** fix the matching setting and reload the app.

> [!NOTE]
>
> You can customize the appearance and colors of your AI agent on your Chatbase dashboard. Go to your **dashboard**, choose an AI agent, click **Channels** in the left sidebar, click **Manage** on the **Chat Bubble** card, then open the **Display** tab to edit Content, Capabilities, Colors, Floating bubble, and Localization.

## Frequently asked questions

> [accordion] Does hiding the HTML element hide the Chat Bubble?
>
> Not once the script has run. The Chat Bubble is added to the page itself, outside the HTML element, so hiding or collapsing the element afterwards leaves the bubble in place. Whether the script runs at all when the element starts hidden depends on how Bubble handles hidden elements.

> [accordion] Do I need separate setups for version-test and live?
>
> No. Both versions use the same script. If you use **Specific domains**, one entry for your `bubbleapps.io` host covers both, because paths are ignored.

> [accordion] How does the chat behave for mobile users of my Bubble app?
>
> Below 640px wide, the chat opens full screen and the page behind it stops scrolling while it's open.

> [accordion] Can I pass the logged-in Bubble user to the AI agent?
>
> The Chat Bubble script supports [identity verification](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md), which lets your app tell Chatbase who the user is. Follow that guide to add it to your Bubble app.

## Next steps

> [card] [Customize the Chat Bubble](https://chatbase.co/docs/user-guides/chatbot/channels.md#chat-bubble-display)
>
> Match the widget to your brand colors, position, and copy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.