> ## 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 Squarespace site

> Embed the SmartAlex AI voice and chat widget on Squarespace with Code Injection or a Code block. Copy-paste snippet, variant choice, and preview gotchas.

Squarespace does not run a plugin marketplace for third-party scripts, so the honest, supported way to add a Squarespace voice AI is the same one every custom tool uses: paste one small script tag. That single tag loads the SmartAlex widget, which handles both voice and chat with Alex, our in-app assistant. Everything the visitor sees (the variant, the colours, which agent answers) is read live from your workspace at load time, so you paste once and restyle later without touching Squarespace again.

<Note>
  Code Injection and Code blocks are available on Squarespace **Business and Commerce plans**. The legacy Personal plan does not include custom code, so the widget will not load there. This applies to both Squarespace 7.0 and 7.1.
</Note>

## How the embed works

```mermaid theme={null}
flowchart LR
  A[Widget Studio: publish variant, colours, agent] --> B[Paste one script tag in Squarespace footer]
  B --> C[Visitor loads your page]
  C --> D[Widget fetches its live config from SmartAlex]
  D --> E[Alex answers by voice and chat]
```

The script tag never contains your colours or variant. It carries one attribute, `data-tenant-id`, and the widget resolves the rest from the server. That is why a design change in Widget Studio is instant and never needs a re-paste.

## Before you start

<Steps>
  <Step title="Confirm your plan">
    Open **Settings** and check you are on a Business or Commerce plan. If Code Injection is missing from the Advanced menu, you are on Personal and need to upgrade first.
  </Step>

  <Step title="Grab your tenant id">
    In SmartAlex, open the widget code panel in Widget Studio and copy `YOUR_TENANT_ID`. If you drive SmartAlex from an AI client over MCP, the tool `smartalex_get_widget_install_code` returns the exact snippet for you.
  </Step>

  <Step title="Pick and publish a variant">
    Choose a variant in Widget Studio (see the table below) and save it as active. Only one widget is active per workspace at a time, so saving one turns the others off.
  </Step>
</Steps>

## Method 1: Code Injection (whole site)

This is the recommended path. It puts the widget on every page in one place.

<Steps>
  <Step title="Open Code Injection">
    Go to **Settings > Advanced > Code Injection**.
  </Step>

  <Step title="Paste into the Footer field">
    Paste the snippet into the **Footer** box (not Header). The footer injects just before the closing `</body>` tag site-wide, which is where an `async` widget belongs.
  </Step>

  <Step title="Save and publish">
    Click **Save**. Injected code runs only on your live, published site, not inside the Squarespace editor preview, so open the real URL in a normal browser tab to test.
  </Step>
</Steps>

## Method 2: Code block (one page)

Use this when you only want the widget on a single page, for example a contact or pricing page.

<Steps>
  <Step title="Add a Code block">
    Edit the page, click an insert point, and add a **Code** block.
  </Step>

  <Step title="Paste the snippet">
    Paste the same script tag. Leave the block set to **HTML** and turn **Display Source** off so the code runs instead of showing as text.
  </Step>

  <Step title="Save and view live">
    Code blocks do not execute scripts in the editor preview. Save, then check the published page.
  </Step>
</Steps>

## The snippet

Paste this exactly and replace `YOUR_TENANT_ID` with your real tenant id. Both forms below are identical to the widget; use whichever reads cleaner in your Code Injection box.

<CodeGroup>
  ```html Formatted 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 Single line 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>

<Warning>
  There is no `data-variant`, `data-agent`, or `data-color` attribute. `data-tenant-id` is the only one. If you find yourself editing anything else in the tag, you are configuring the wrong place: the variant and colours live in Widget Studio.
</Warning>

## Choosing a variant

Set the variant once in Widget Studio. The snippet stays byte-identical across all five.

| Widget Studio label | Docs label | Interaction           | Best for                                             |
| ------------------- | ---------- | --------------------- | ---------------------------------------------------- |
| Pill (default)      | Pill       | Voice first plus chat | A calm floating button that expands into chat        |
| Chat Bar            | Chat bar   | Text                  | An always-visible input bar along the bottom         |
| Side Panel          | Side panel | Text                  | A full-height panel that slides in from the right    |
| Voice Pill          | Voice pill | Voice only            | A voice-only pill with an avatar and call button     |
| Widget v2           | Ask Alex   | Voice plus text       | A premium voice and chat messenger, live on the page |

<Info>
  Naming to expect: the same premium variant is labelled **Widget v2** in Studio and **Ask Alex** in these docs. It is one variant with two names. The **Voice Pill** and **Ask Alex** variants only appear in the picker when your agent runs on the SmartAlex voice engine. **Ask Alex** also turns on persistent pop-up calls so a call survives page navigation.
</Info>

## Restyle without re-pasting

Because the widget reads its config from the server, you change the look entirely inside SmartAlex:

* Open Widget Studio, pick a new variant or new colours, and save.
* The published Squarespace page updates on the next visitor load. No Code Injection edit, no republish of the tag.

The Squarespace snippet is a permanent anchor. Everything visual is a workspace setting.

## Let an AI agent wire it for you

SmartAlex is agent-native, so you can have Claude Code, Cursor, or ChatGPT fetch the exact tag and hand it to you. Connect the hosted MCP server once:

```bash theme={null}
claude mcp add --transport http smartalex https://api.getsmartalex.com/functions/v1/mcp-server
```

Then prompt your assistant:

> Get my SmartAlex widget install code and give me the exact script tag to paste into Squarespace Code Injection.

The assistant calls `smartalex_get_widget_install_code` and returns the snippet with your tenant id already filled in. Generating MCP API keys for local use requires the Power Tools add-on (\$29/mo) and a super-admin role; the hosted command above uses a browser sign-in and needs no key.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The widget does not appear on my live site">
    Confirm you are on a Business or Commerce plan, check that `YOUR_TENANT_ID` was replaced with your real id, and hard refresh (the script is cached). Make sure one widget config is saved as active in Widget Studio.
  </Accordion>

  <Accordion title="It works in the editor preview but not for visitors, or the reverse">
    Squarespace runs injected code and Code blocks only on the published site, not in the editor preview. Always test on the real URL in a normal browser tab.
  </Accordion>

  <Accordion title="I pasted the tag twice and see two widgets">
    Only add the snippet in one place. If it is in Code Injection Footer, do not also add a per-page Code block, or the widget loads twice.
  </Accordion>

  <Accordion title="Voice Pill or Ask Alex is missing from the picker">
    Those two variants require an agent deployed to the SmartAlex voice engine. Pill, Chat bar, and Side panel are always available.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Widget install reference" href="/essentials/widget-install">
    The canonical install guide, including the React and Next.js versions of the same snippet.
  </Card>

  <Card title="Widget variants" href="/essentials/widgets">
    A closer look at all five variants and how to style them in Widget Studio.
  </Card>

  <Card title="Build with SmartAlex" href="/build-with/overview">
    Embed guides for Webflow, Framer, WordPress, Shopify, Wix, and more.
  </Card>

  <Card title="Operate from an AI client" href="/mcp/overview">
    Connect Claude, Cursor, or ChatGPT to your workspace over the live MCP server.
  </Card>
</CardGroup>