> ## 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 an AI voice widget to your website

> Embed an AI voice agent on your website in minutes. Add AI voice chat to any site (React, WordPress, Shopify, and more) with a single script tag.

Put a talking agent on your website that greets visitors, answers questions from your knowledge base, books meetings, captures leads, and hands off to a human when it matters. You build the agent once, pick a widget style, and paste a single script tag. That is all it takes to add AI voice chat to your website.

This recipe covers the five widget styles, how to choose one, and how to install it on the platforms most teams use. For the full reference, see [Widget variants](/essentials/widgets) and the [install guide](/essentials/widget-install).

## The five widget styles

Widget Studio ships five variants. Only one is active per workspace at a time, so you pick the experience that fits your page and everyone who visits sees the same thing.

| Variant        | Mode                   | What visitors see                                                              |
| -------------- | ---------------------- | ------------------------------------------------------------------------------ |
| Pill (default) | Voice first, with chat | A compact floating button that expands into a voice call, with a text fallback |
| Voice pill     | Voice only             | A floating voice button for one tap, hands free conversation                   |
| Chat bar       | Text                   | A docked bar along the bottom of the page for typed questions                  |
| Side panel     | Text                   | A slide out panel with full conversation history                               |
| Ask Alex       | Voice and text         | A full messenger where visitors can speak or type in one thread                |

<Note>
  Every variant is powered by the same agent you build in Studio. Switching styles never changes the agent's instructions, knowledge, or tools. It only changes how the conversation appears on the page.
</Note>

## Pick the right variant

Match the style to the intent of the page, not the other way around.

* **High intent landing pages and pricing pages.** Use the **Pill** (default). Voice first converts curiosity into a real conversation, and the text fallback catches visitors who cannot talk out loud.
* **Product tours, demos, or a hero built around talking.** Use the **Voice pill** for a clean, one tap "press to speak" moment with nothing else on screen.
* **Support docs and help centres.** Use the **Chat bar** or **Side panel** so visitors can keep reading while they type, and scroll back through history.
* **A full assistant experience.** Use **Ask Alex** when you want a rich messenger that lets people switch between speaking and typing in the same thread.

<Tip>
  Not sure? Start with the Pill. It is the most flexible because it offers both voice and text, and you can switch variants later without touching your site again.
</Tip>

## Add the widget to your site

<Steps>
  <Step title="Build or pick your agent">
    In [Studio](/studio/create-agent), create the agent that will greet visitors. Add your knowledge (scan your website or paste details), choose a voice, and switch on the [tools](/essentials/agent-tools) it should use, for example Check availability, Create booking, Create lead, or Transfer call. Run a test call from the composer before you ship.
  </Step>

  <Step title="Choose a widget style">
    Open Widget Studio and select one of the five variants above. Set the greeting, position, and brand colour so it matches your site.
  </Step>

  <Step title="Copy the script tag">
    Widget Studio generates one script tag scoped to your workspace and agent. Copy it. The exact tag is in your dashboard. It looks like this:

    ```html theme={null}
    <!-- Copy the exact tag from Widget Studio. This shows the shape. -->
    <script
      src="https://widget.getsmartalex.com/v1/embed.js"
      data-workspace="your-workspace-id"
      async
    ></script>
    ```
  </Step>

  <Step title="Paste it into your site">
    Add the tag once, just before the closing `</body>` tag on every page you want the widget to appear. See the platform notes below for the exact spot on your stack. Publish, reload the page, and the widget appears in the corner.
  </Step>
</Steps>

## Platform notes

The tag is plain HTML, so it works anywhere you can add a script. Here is where it goes on the platforms teams ask about most. The [install guide](/essentials/widget-install) has copy and paste steps for each.

<AccordionGroup>
  <Accordion title="React, Next.js, and single page apps">
    Add the tag to your root `index.html` (or the document `<head>` in a framework layout) so it loads once for the whole app. If you prefer to inject it in code, append the script on mount:

    ```jsx theme={null}
    import { useEffect } from "react";

    export function VoiceWidget() {
      useEffect(() => {
        const s = document.createElement("script");
        s.src = "https://widget.getsmartalex.com/v1/embed.js";
        s.dataset.workspace = "your-workspace-id";
        s.async = true;
        document.body.appendChild(s);
        return () => s.remove();
      }, []);
      return null;
    }
    ```

    The widget persists across client side route changes, so a visitor mid conversation stays connected as they navigate. Load the script once, not per route.
  </Accordion>

  <Accordion title="WordPress">
    Easiest path: paste the tag into a **Custom HTML** block on the pages you want, or use a header and footer scripts plugin and drop it in the footer so it loads site wide. If you edit your theme directly, add it to `footer.php` just before the closing body tag. No plugin is required.
  </Accordion>

  <Accordion title="Shopify">
    Go to **Online Store, Themes, Edit code**, open `theme.liquid`, and paste the tag just before the closing `</body>` tag. It will then load on every storefront page. To limit it to specific pages, add it to a custom section or template instead.
  </Accordion>

  <Accordion title="Wix and Squarespace">
    On **Wix**, open **Settings, Custom Code**, add a new snippet, paste the tag, and set it to load on all pages in the body. On **Squarespace**, open **Settings, Advanced, Code Injection** and paste the tag into the **Footer** field.
  </Accordion>
</AccordionGroup>

## What happens when a visitor talks to the widget

```mermaid theme={null}
flowchart LR
  A[Visitor opens the widget] --> B{Voice or text}
  B -->|Voice| C[Your agent answers by voice]
  B -->|Text| D[Your agent replies in chat]
  C --> E[Agent runs its tools]
  D --> E
  E --> F[Books, quotes, captures the lead, or transfers to a person]
  F --> G[Saved to call logs and your CRM]
```

Voice conversations run on the SmartAlex voice engine: curated, high accuracy speech, language, and voice models, kept abstracted so you never manage a vendor. Every session is logged, so you can review transcripts and outcomes in [call logs](/essentials/call-logs) and [analytics](/essentials/analytics).

## Good to know

* **One widget per workspace.** Only one variant is live at a time. Change it in Widget Studio whenever you like; you do not need to edit your site again.
* **Usage draws from your wallet.** Web conversations are billed from your prepaid wallet at a blended average of \$0.05/min. See [pricing](/pricing) for plan details and included minutes.
* **The agent uses the same brain everywhere.** Knowledge, voice, and tools are shared with your phone and campaign agents. Update the [knowledge base](/essentials/knowledge-base) once and the widget stays current.
* **Connect your own systems.** Book against your calendar, send a payment link, or reach into your own APIs. Custom HTTP Tools and the [MCP server](/mcp/overview) are the live way to wire the agent into your stack. A public REST API and TypeScript SDK are in private beta; contact support for early access.

## Related

<CardGroup cols={2}>
  <Card title="Widget variants" icon="puzzle-piece" href="/essentials/widgets">
    Every style, setting, and behaviour in Widget Studio.
  </Card>

  <Card title="Install the widget" icon="code" href="/essentials/widget-install">
    Copy and paste steps for WordPress, Shopify, Wix, Squarespace, and React.
  </Card>

  <Card title="Create your agent" icon="robot" href="/studio/create-agent">
    Build, test, and voice the agent that powers your widget.
  </Card>

  <Card title="Agent tools" icon="wand-magic-sparkles" href="/essentials/agent-tools">
    Let the widget book, quote, capture leads, and hand off to people.
  </Card>
</CardGroup>