Skip to main content
Bubble is a no-code visual builder, and SmartAlex is a no-code voice platform, so wiring them together is a copy and paste job. There is no Bubble plugin to install and no API to call. You drop one script tag into your Bubble app, and a floating voice and chat widget appears on the front end. Your visitors can talk or type to Alex, your AI agent, and the conversations, contacts, and deals flow into your SmartAlex workspace.
The widget is the fastest way to add AI voice AI to a Bubble app. If you want an AI client (Claude, Cursor, ChatGPT) to operate your SmartAlex account instead, see Connect via MCP. The two are complementary.

​
How the pieces fit

The script tag loads a small loader file. That loader reads your published widget configuration (variant, colors, and which agent answers) from SmartAlex at page load, so you never have to hardcode any of that in Bubble. Because the config lives on the server, restyling the widget in Widget Studio never means editing Bubble again. The snippet is byte for byte identical no matter which variant you pick.

​
Get your install snippet

1

Open the widget code panel in SmartAlex

In your SmartAlex dashboard, open Widget Studio and find the install code panel. It shows the script tag with your real workspace ID already filled in. Prefer to work from an AI client? The MCP tool smartalex_get_widget_install_code returns the same snippet.
2

Copy your tenant ID

The only value you ever change is data-tenant-id. It is your workspace UUID. Everything else is fixed.
The snippet is a single self contained tag:
Replace YOUR_TENANT_ID with your workspace UUID. That is the whole configuration. Use this when you want the widget on every page of your Bubble app. It survives navigation and only has to be pasted once.
1

Open your app settings

In the Bubble editor, go to the Settings tab, then the SEO / metatags sub tab.
2

Paste into the header field

Find Script/meta tags in header and paste the snippet there. This injects the tag into the head of every page in your app.
3

Deploy to live

Header scripts run on the deployed app. Click Deploy to push to live, then open your live URL to see the widget.
Adding executable script tags in the header field requires a paid Bubble plan (custom code). If you are on the free tier, use Option B, which works on any plan.

​
Option B: HTML element on one page

Use this when you only want the widget on a specific page, or you want to place it precisely inside a Bubble layout.
1

Drag in an HTML element

From the visual elements palette, under Visual elements, drag an HTML element onto the page. A small hidden element is fine, since the widget renders as a floating overlay, not inside the box.
2

Paste the snippet

Double click the HTML element and paste the snippet into its content field.
3

Preview

Click Preview to load the page. The floating widget appears anchored to the browser window, not to the element’s position.
Keep the HTML element out of a repeating group or a reusable element that renders many times. Placing it once per page means the loader runs once and you get a single widget instead of duplicates.

​
Choose your widget variant

You pick the look and interaction style inside Widget Studio, not in Bubble. Save the one you want, mark it active, and the loader serves it. Only one widget is active per workspace at a time.
The “Ask Alex” variant is the same one labelled Widget v2 inside Widget Studio (internal id ask_alex_v2). Same widget, a couple of different names across the product. The voice only and Ask Alex variants appear in the picker only when your agent is deployed on the SmartAlex voice engine. The Pill, Chat bar, and Side panel variants are always available.
Your voice stack is curated, high accuracy speech, language, and voice models, kept abstracted, so there is nothing to configure and no vendor to wire up on the Bubble side.

​
Test it and go live

  • In Bubble, Preview runs the development version and Deploy publishes to live. The widget works in both once the tag is present.
  • Open the widget, send a message, then check your SmartAlex dashboard. A new contact and call record should appear.
  • Restyle any time in Widget Studio. Changes take effect on the next page load with no Bubble edit and no redeploy.

​
Bubble specific gotchas

  • Free plan. Header scripts need a paid Bubble plan. Use the HTML element (Option B) if you are on free.
  • Responsive engine. The widget floats above your page in a fixed position, so Bubble’s responsive layout and breakpoints do not affect it. You do not need to reserve space for it.
  • One instance. Do not paste the snippet in both the header and an HTML element on the same page, and keep it out of repeating groups, or you may load two widgets.
  • Privacy and pop-ups. If your Bubble app uses a consent banner or a script blocker, make sure api.getsmartalex.com is allowed so the loader can fetch its config.

​
Going further

The widget is enough for most Bubble sites. When you want the agent to act on your own systems during a call, for example look up a booking or take a payment, add Custom HTTP Tools so the agent calls your own HTTPS endpoint mid conversation. Custom HTTP Tools are part of the Power Tools add-on ($29/mo on Professional, included on Enterprise). See pricing for the full breakdown.

Full install reference

Every embed target, the React and Next.js version, and how to find your tenant ID.

Widget install guide

The canonical snippet, variants, and troubleshooting for any site.

Widgets overview

What each widget variant does and when to use it.

Next.js and Vercel

Embedding the widget in a React or Next.js front end instead.

Build with overview

Every platform and AI client you can wire SmartAlex into.