SmartAlex Documentation - AI Voice Assistant Platform

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

Build the agent

Two ways in, same result.In the app: open the Composer, 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 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):

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

Pick a widget variant

In Widget Studio, 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.

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.

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.

// 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}</>;
}

<!-- 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>

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.

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.

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.

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

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.

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

Widget Studio

Configure the variant, appearance, and answering agent before you install.

Installing the widget

Copy-paste guides for React, WordPress, Shopify, Wix, and Squarespace.

Cursor, v0, and Bolt

The same voice widget in other AI-native builders and editors.

Build with Claude Code

Create and manage agents end to end over the MCP server.

​How it fits together

​Paste it into your Lovable project

​Works for any React or static site

​Related

Widget Studio

Installing the widget

Cursor, v0, and Bolt

Build with Claude Code

How it fits together

Paste it into your Lovable project

Works for any React or static site

Related