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

> Embed the SmartAlex voice and chat widget on WordPress with a Custom HTML block or a header/footer script. No plugin required.

You can add an AI voice agent and a chat widget to any WordPress site by pasting one script tag. There is no SmartAlex plugin to install, and you do not need one. The widget is a single async script that reads its own published configuration (variant, colours, agent) from the server at load time, so the identical snippet works on a classic theme, a block theme, or a page builder like Elementor or Divi.

If you searched for a "WordPress AI phone widget" or a way to add AI chat to WordPress, this is the whole job: get your tenant ID, drop in the snippet, publish.

<Note>
  There is no official "SmartAlex plugin" in the WordPress directory. Anything claiming to be one is not ours. The real, supported path is the script tag on this page (or the [React component](/essentials/widget-install) if your theme is headless).
</Note>

## Before you start

<Steps>
  <Step title="Have a SmartAlex workspace with a published agent">
    Build one in [Studio](/studio/overview). You can point Studio at your website URL and it drafts an agent in under 60 seconds, or [create one from scratch](/studio/create-agent).
  </Step>

  <Step title="Copy your tenant ID">
    Open the widget code panel in SmartAlex (Widget Studio). The `data-tenant-id` value is a UUID unique to your workspace. If you drive the account from an AI client over MCP, the tool `smartalex_get_widget_install_code` returns the same snippet.
  </Step>
</Steps>

## The snippet

This is the exact tag. Replace `YOUR_TENANT_ID` with your workspace UUID. The `data-tenant-id` attribute is the only one you set: colour, layout, and which agent answers are all controlled from Widget Studio, not from the markup.

```html 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>
```

Because styling lives server-side, restyling the widget later never means editing WordPress again. You change it once in Studio and every page updates.

## Two ways to embed it

Pick based on where you want the widget to appear.

<CardGroup cols={2}>
  <Card title="Whole site (recommended)" icon="globe">
    Inject the script into the site footer so it loads on every page and post.
  </Card>

  <Card title="One page or post" icon="file">
    Drop a Custom HTML block into a single page when you only want it there.
  </Card>
</CardGroup>

### Site-wide: header or footer injection

The cleanest no-code route is a "header and footer scripts" plugin (for example WPCode, Insert Headers and Footers, or Header Footer Code Manager). These let you add markup to every page without touching theme files.

<Steps>
  <Step title="Install a header/footer scripts plugin">
    From your WordPress dashboard, go to Plugins, then Add New, and install any reputable headers-and-footers plugin. Activate it.
  </Step>

  <Step title="Paste the snippet into the footer slot">
    Open the plugin's settings, find the "Footer" (or "Before \</body>") field, and paste the script tag. The footer slot is preferred because the widget loads after your page content.
  </Step>

  <Step title="Save and clear caches">
    Save. If you run a caching or CDN plugin (WP Rocket, W3 Total Cache, LiteSpeed, or Cloudflare), purge the cache so visitors get the updated page.
  </Step>
</Steps>

<Tip>
  Editing a classic theme directly instead? Add the snippet just before the closing `</body>` tag in your child theme's `footer.php`. Always use a child theme so a theme update does not overwrite it. Block themes do not expose `footer.php`, so use the plugin route above.
</Tip>

### One page: Custom HTML block

For a single landing page or contact page in the block (Gutenberg) editor:

<Steps>
  <Step title="Add a Custom HTML block">
    Edit the page, click the plus to add a block, search for "Custom HTML", and insert it.
  </Step>

  <Step title="Paste the snippet">
    Paste the same script tag into the block.
  </Step>

  <Step title="Update the page">
    Click Update. Preview the live page (not just the editor) to see the widget load.
  </Step>
</Steps>

<Warning>
  A Custom HTML block only renders the widget on the page that contains it. For a persistent widget across the whole site, use the footer injection method instead.
</Warning>

## How it loads

```mermaid theme={null}
flowchart LR
  A[Visitor opens a WordPress page] --> B[Async script tag runs]
  B --> C[Reads data-tenant-id]
  C --> D[Fetches your published widget config]
  D --> E{Configured variant}
  E -->|Pill / Chat bar / Side panel| F[Chat with Alex]
  E -->|Voice pill / Ask Alex| G[Live voice call with Alex]
```

## Choosing a widget variant

You set the variant in Widget Studio, not in the WordPress markup. Five are available:

| Variant        | Interaction           | Good for                                           |
| -------------- | --------------------- | -------------------------------------------------- |
| Pill (default) | Voice-first plus chat | Most sites: a compact floating button that expands |
| Chat bar       | Text                  | An always-visible input bar along the bottom       |
| Side panel     | Text                  | A full-height panel that slides in from the right  |
| Voice pill     | Voice only            | A tap-to-call pill with an avatar                  |
| Ask Alex       | Voice plus text       | A premium messenger with persistent pop-up calls   |

<Note>
  The voice-only variants (Voice pill and Ask Alex) appear in the picker only when your agent runs on the SmartAlex voice engine. The text variants (Pill, Chat bar, Side panel) are always available. Only one widget is active per workspace at a time, and saving a new active widget switches the previous one off. See [widgets](/essentials/widgets) for the full breakdown.
</Note>

## Verify it is live

Open your published site in a normal browser tab (not the WordPress editor) and hard refresh. The widget should appear in the corner. If it does not:

* Confirm `YOUR_TENANT_ID` is your real UUID, with no quotes or spaces left over.
* Purge every caching layer (page cache plugin and CDN). Stale HTML is the most common cause.
* Check that a security or "script blocker" plugin has not stripped the tag. Allowlist the `api.getsmartalex.com` host if needed.
* If you used a Custom HTML block, remember it only shows on that one page.

## Going further

The widget is one of three ways to plug SmartAlex into your stack. You can also drive the whole account from an AI client over the [MCP server](/mcp/overview), and let your agent call your own WordPress or CRM endpoints mid-call with [Custom HTTP Tools](/essentials/agent-tools). Custom HTTP Tools and MCP keys are unlocked by the Power Tools add-on at \$29/mo (see [add-ons](/essentials/add-ons)); full plan pricing is on [/pricing](/pricing).

## Related

<CardGroup cols={2}>
  <Card title="Widget install reference" icon="code" href="/essentials/widget-install">
    The canonical snippet, React usage, and every install detail.
  </Card>

  <Card title="Widget variants" icon="layout" href="/essentials/widgets">
    Compare all five widget styles and when to use each.
  </Card>

  <Card title="Build-with overview" icon="wrench" href="/build-with/overview">
    Every platform and AI client you can connect SmartAlex to.
  </Card>

  <Card title="Operate SmartAlex over MCP" icon="terminal" href="/mcp/overview">
    Connect Claude, Cursor, or ChatGPT to run your account.
  </Card>
</CardGroup>