Use this guide to install the AI Agent widget on Bubble apps.
Copy the Embed Code from your portal as described in Installation Overview.Two embed methods are supported:1.
Script-based loader (recommended): Adds an AI Agent bubble. The chat opens in an iframe popover when the visitor clicks the bubble.
2.
Iframe-based embed: Loads the AI Agent directly as an iframe appended to the page body (best for a dedicated page).
Best placement#
Script-based loader: Add it globally so it loads across pages (Bubble global HTML/script area).
Iframe-based embed: Add it only on a specific page where you want a direct embedded chat experience.
The embed code appends to document.body. Later placement is safer.
Script-based loader (AI Agent Bubble)#
3.
Open the area that allows adding global HTML/scripts (commonly SEO / Metatags or similar).
4.
Paste the Script-based loader code in the global script area.
If Bubble offers separate fields for header vs body/footer scripts, choose the option that runs later.
Iframe-based embed (Direct AI Agent Chat)#
This method appends the iframe to the page body and is best used on a dedicated page.1.
Open the page where you want the embedded AI Agent.
2.
Add an HTML element (or any element that allows custom HTML/scripts).
3.
Paste the Iframe-based embed code.
To control size, adjust iframe.style.width and iframe.style.height in the code (example: 600px, 80vh, 100vh).
Even when placed inside an HTML element, the iframe is appended to the page body (because the code uses document.body.appendChild(...)).
Verify installation#
1.
Open the live Bubble app in an incognito/private window.
2.
Confirm the bubble or embedded AI Agent loads.
3.
Send a test message and confirm replies.
Troubleshooting#
Confirm you deployed to live (not only preview).
Hard refresh (Ctrl+Shift+R / Cmd+Shift+R).
Check Bubble conditions/workflows that may hide elements or prevent scripts from running.
If added globally, confirm the global script is included on the current page.
Check browser console for errors or blocked requests.
Test without browser extensions (ad blockers, privacy tools).
Ensure the code is not placed both globally and inside multiple pages where it runs twice.
Ensure multiple global script entries are not loading the same embed code.
Modified at 2026-02-19 07:25:45
