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

# Add AI voice to a Bubble app

> Embed the SmartAlex AI voice and chat widget in a Bubble app with one script tag. Add an AI chat widget to Bubble via the page header or an HTML element, then pick a variant.

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.

<Note>
  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](/mcp/getting-started). The two are complementary.
</Note>

## 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.

```mermaid theme={null}
flowchart LR
  A[Visitor opens<br/>your Bubble page] --> B[Bubble renders<br/>the script tag]
  B --> C[Loader fetches your<br/>published widget config]
  C --> D[Widget renders in<br/>your chosen variant]
  D --> E[Visitor talks or types<br/>to Alex]
  E --> F[Contacts, calls and deals<br/>land in SmartAlex]
```

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Copy your tenant ID">
    The only value you ever change is `data-tenant-id`. It is your workspace UUID. Everything else is fixed.
  </Step>
</Steps>

The snippet is a single self contained tag:

<CodeGroup>
  ```html Widget snippet theme={null}
  <!-- SmartAlex Widget -->
  <script
    src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js"
    data-tenant-id="YOUR_TENANT_ID"
    async>
  </script>
  ```

  ```html One line version theme={null}
  <script src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js" data-tenant-id="YOUR_TENANT_ID" async></script>
  ```
</CodeGroup>

Replace `YOUR_TENANT_ID` with your workspace UUID. That is the whole configuration.

## Option A: app-wide header (recommended)

Use this when you want the widget on every page of your Bubble app. It survives navigation and only has to be pasted once.

<Steps>
  <Step title="Open your app settings">
    In the Bubble editor, go to the **Settings** tab, then the **SEO / metatags** sub tab.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Paste the snippet">
    Double click the HTML element and paste the snippet into its content field.
  </Step>

  <Step title="Preview">
    Click **Preview** to load the page. The floating widget appears anchored to the browser window, not to the element's position.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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.

| Variant (docs label) | Interaction          | Best for a Bubble app that wants                  |
| -------------------- | -------------------- | ------------------------------------------------- |
| Pill (default)       | Voice first and chat | A compact button that expands into a conversation |
| Chat bar             | Text                 | An always visible input bar pinned to the bottom  |
| Side panel           | Text                 | A full height panel that slides in from the right |
| Voice pill           | Voice only           | A tap to call button with an agent avatar         |
| Ask Alex             | Voice and text       | A premium messenger with persistent voice calls   |

<Note>
  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.
</Note>

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](/pricing) for the full breakdown.

<Card title="Full install reference" icon="code" href="/essentials/widget-install">
  Every embed target, the React and Next.js version, and how to find your tenant ID.
</Card>

## Related

<CardGroup cols={2}>
  <Card title="Widget install guide" icon="code" href="/essentials/widget-install">
    The canonical snippet, variants, and troubleshooting for any site.
  </Card>

  <Card title="Widgets overview" icon="window" href="/essentials/widgets">
    What each widget variant does and when to use it.
  </Card>

  <Card title="Next.js and Vercel" icon="react" href="/build-with/nextjs-vercel">
    Embedding the widget in a React or Next.js front end instead.
  </Card>

  <Card title="Build with overview" icon="layer-group" href="/build-with/overview">
    Every platform and AI client you can wire SmartAlex into.
  </Card>
</CardGroup>