> ## 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 Lovable app

> Give a Lovable-generated site a talking AI agent: build the agent in the SmartAlex Composer or over MCP, then drop in one widget script tag or a React component.

Lovable ships you a working React app in minutes. This guide gives that app a voice: a floating agent your visitors can talk to, powered by SmartAlex. You build the agent once, then embed it with a single script tag or a small React component. The same steps work for any Lovable, v0, Bolt, Replit, or plain static site.

SmartAlex is agent-native by design, so you can do the whole thing from a chat with Claude Code or another MCP client, or click through the dashboard. Both paths land in the same place.

## How it fits together

```mermaid theme={null}
flowchart LR
    A["Build the agent<br/>(Composer or MCP)"] --> B["Pick a widget variant<br/>in Widget Studio"]
    B --> C["Copy the install code<br/>(panel or MCP tool)"]
    C --> D["Paste into your<br/>Lovable project"]
    D --> E["Visitors talk to<br/>your agent"]
```

<Steps>
  <Step title="Build the agent">
    Two ways in, same result.

    **In the app:** open the [Composer](/studio/create-agent), describe the agent in plain English, or point it at your website URL and let it scrape the business, write an optimized prompt, and deploy a live agent in about 30 to 60 seconds. Set the name, first message, and voice, then toggle it active.

    **Over MCP:** connect your AI client to the live [MCP server](/mcp/getting-started) and ask it to build the agent for you. For Claude Code, connect over the hosted cloud endpoint (OAuth in the browser, no API key, no config file):

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

    Then just ask: "Create a voice agent from example.com and give me the widget install code." The `smartalex_create_agent` tool builds and deploys the agent, and `smartalex_get_widget_install_code` returns the exact snippet to paste. ChatGPT, Cursor, VS Code, and Windsurf connect to the same server (see [supported clients](/mcp/overview)).
  </Step>

  <Step title="Pick a widget variant">
    In [Widget Studio](/essentials/widgets), choose how the agent appears and which agent answers. For a Lovable landing page, two variants cover most cases:

    * **Voice pill** (`voice_pill`): a compact floating button, voice only. Best when you want the fastest "tap to talk" call to action.
    * **Ask Alex** (`ask_alex_v2`): a full messenger with both voice and text, so visitors can type or talk. Good for support and richer conversations.

    The default `pill` variant is voice-first with a chat fallback and is a safe choice if you are unsure. One widget is active per workspace at a time. You can restyle the colour, position, and greeting here later without touching your site again.
  </Step>

  <Step title="Copy your install code">
    Grab your `data-tenant-id` from the widget code panel in the app, or from the MCP tool if you built over MCP. Then paste one of the two snippets below into your Lovable project.
  </Step>
</Steps>

## Paste it into your Lovable project

Lovable outputs a React app, so use the component method. If you ever export a static build (or you are on a plain HTML site), the script tag works too.

<CodeGroup>
  ```jsx React component (Lovable, v0, Bolt) theme={null}
  // Add to your root layout or App component
  import { useEffect } from 'react';

  export default function Layout({ children }) {
    useEffect(() => {
      const script = document.createElement('script');
      script.src = 'https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js';
      script.setAttribute('data-tenant-id', 'YOUR_TENANT_ID');
      script.async = true;
      document.body.appendChild(script);

      return () => {
        document.body.removeChild(script);
      };
    }, []);

    return <>{children}</>;
  }
  ```

  ```html Script tag (static or HTML export) 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>
  ```
</CodeGroup>

Swap `YOUR_TENANT_ID` for your real value. There is no package to install: it is a single external script loaded from the SmartAlex storage host, so it will not touch your bundle or add dependencies.

<Tip>
  In Lovable, tell the builder exactly what you want: "Add this script to the root layout inside a useEffect and clean it up on unmount." Paste the component above and it will wire it in for you.
</Tip>

<Note>
  The widget reads its published configuration (variant, colours, agent) at load time. Change the look or swap the answering agent in Widget Studio and the live site updates on the next page load, no redeploy required.
</Note>

## Works for any React or static site

Nothing here is specific to Lovable. The React component drops into any React or Next.js app (v0, Bolt, Replit, or hand-written). The script tag works on any static or CMS site, with the same one-line install used for [WordPress, Shopify, Wix, and Squarespace](/essentials/widget-install).

The voice itself runs on a curated, high-accuracy stack of speech, language, and voice models, kept abstracted, so there is nothing for you to tune or wire up. Your visitors get a fast, natural conversation and you keep a plain script tag.

<Info>
  Building programmatically today happens over the live MCP server and Custom HTTP Tools. A public REST API and a TypeScript SDK are in private beta and coming soon. For now, the widget embeds via the script tag or the React component above, which is all a Lovable site needs.
</Info>

You can start on the free tier for browser voice, or see [pricing](/pricing) for included minutes, telephony, and add-ons.

## Related

<CardGroup cols={2}>
  <Card title="Widget Studio" icon="puzzle-piece" href="/essentials/widgets">
    Configure the variant, appearance, and answering agent before you install.
  </Card>

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

  <Card title="Cursor, v0, and Bolt" icon="wand-magic-sparkles" href="/build-with/cursor-v0-bolt">
    The same voice widget in other AI-native builders and editors.
  </Card>

  <Card title="Build with Claude Code" icon="robot" href="/build-with/claude-code">
    Create and manage agents end to end over the MCP server.
  </Card>
</CardGroup>