> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the Voiceflow widget to Lovable

> Add a Voiceflow AI agent to your Lovable app with the supplied chat widget. Use Build mode or your linked repository, handle server rendering and test before publishing.

## Overview

Add Voiceflow’s floating chat widget to your Lovable app so visitors can ask your AI agent about your products, policies or services. **Studio** uses Lovable’s Build mode; **Code** adds the same installation through your linked repository. Both keep the supplied widget and load it once in the browser.

This guide covers Lovable’s current TanStack Start projects and older React + Vite projects. You do not need to migrate your app to install the widget.

**Note:** 

**Building your own interface?** Custom chat and voice walkthroughs are [coming soon](#custom-interface). Start with [Chat agents](/docs/api-reference/agent-runtime/chat) or [Voice agents](/docs/api-reference/agent-runtime/voice) for the APIs.

New to Voiceflow? [Build a support agent](/docs/guides/usecases/customer-service/build-faq-agent), add your help content to Knowledge and publish it first. This recipe provides public support; it does not connect the widget to your app’s login or protected data.

<a id="before-you-begin"></a>

## Before you begin

Prepare the agent and access to the Lovable project you will update.

| Requirement | What to prepare |
| --- | --- |
| Voiceflow agent | A published agent, its complete **Widget → Installation** snippet and a known-answer question. |
| Lovable project | An existing app with edit access and a preview you can test. |
| Studio method | Access to **Build** mode and sufficient usage credits for the change. |
| Code method | A current checkout of the linked repository and permission to push to its synced branch. Ask the project owner for both. |
| Publishing owner | A teammate allowed to publish the reviewed project. |

In Voiceflow, open **Widget → Modality & interface**. Set **Modality** to **Chat** and **Chat interface** to **Widget**, then publish. Review preview and production hosts if the project restricts widget domains. Keep personal and service API keys out of browser code.

<a id="install-widget"></a>

## Install the widget

Load the generated script from a persistent client-side component.

#### Studio

### 1. Copy your installation snippet

In [Agent studio](https://creator.voiceflow.com), open **Widget → Installation** and copy the complete generated snippet, including its script tags.

### 2. Ask Lovable to install it

Open your Lovable project and choose **Build** in the project-chat mode picker. Send the request below, followed by your complete snippet:

```text
Add Voiceflow's supplied floating chat widget for public support.

Use the JavaScript between my snippet's script tags unchanged in
public/voiceflow-widget.js. Preserve its authorization, URLs and
release configuration. Never add a personal or service API key.

Create src/components/VoiceflowWidget.tsx. In a client-side effect,
append /voiceflow-widget.js to document.body only if a script with
id voiceflow-widget-loader is absent. Give the new script that ID.
If the asset fails to load, remove that script and log the failure.

Render this component once in the persistent root layout for this
project's actual stack. Do not access window or document during
server rendering, or reload/destroy the widget on route changes.
Do not build a replacement chat UI or change authentication.

Run the project build and check navigation for duplicate loaders.
Show the changed files and leave the app unpublished for review.

My complete Voiceflow installation snippet follows:
```

Paste your snippet after the request before sending. [Build mode](https://docs.lovable.dev/features/projects/chat) makes the changes; Chat and Plan modes do not implement this request by themselves.

### 3. Review the result in preview

Review Lovable’s changed-file summary and build result. The installation should have a public JavaScript file, one client-side loader component and one persistent root mount.

Open the preview in a new tab. Confirm that one launcher appears and opens, then complete the [visitor test](#test-conversation). If it fails, give Lovable the failing URL and behavior and ask it to correct the installation before publishing.

#### Code

Use your project’s existing [Git sync connection](https://docs.lovable.dev/integrations/git-sync-overview). Work from its current synced branch; do not create another Lovable project or replace the app’s framework.

### 1. Save the generated JavaScript

Create `public/voiceflow-widget.js` in the linked project. Paste only the JavaScript **between** the opening `<script ...>` and closing `</script>` tags of the generated **Widget → Installation** snippet supplied by the Voiceflow owner.

Keep that JavaScript unchanged, including its loader, `verify`, runtime URLs and environment settings. Do not put HTML script tags in this `.js` file. In this root-hosted app, the file will be served at `/voiceflow-widget.js`.

### 2. Create the client-side component

Create `src/components/VoiceflowWidget.tsx`:

```tsx
import { useEffect } from 'react';

export function VoiceflowWidget() {
  useEffect(() => {
    const id = 'voiceflow-widget-loader';
    if (document.getElementById(id)) return;

    const script = document.createElement('script');
    script.id = id;
    script.src = '/voiceflow-widget.js';
    script.async = true;
    script.onerror = () => {
      script.remove();
      console.error('Voiceflow installation script could not load.');
    };
    document.body.appendChild(script);
  }, []);

  return null;
}
```

The effect runs after the browser mounts the app. The script ID prevents another loader during development effect replays or a later component remount. This site-wide widget stays alive through route changes; no effect cleanup removes it.

### 3. Mount it in the root layout

Import the component in the app’s persistent root and render `<VoiceflowWidget />` once beside its routed content, preserving the existing providers and page structure:

| Project stack | Mount location |
| --- | --- |
| TanStack Start | `src/routes/__root.tsx`, inside the existing body/root layout alongside its routed content. Keep the existing head and framework scripts. |
| Older React + Vite | `src/App.tsx`, inside the existing top-level app wrapper, outside individual page routes. |

Use the relative import for that file: `../components/VoiceflowWidget` from the routes root, or `./components/VoiceflowWidget` from `App.tsx`.

Do not run the generated script at module scope or inside server-rendered HTML. Do not use `dangerouslySetInnerHTML` to execute script markup.

### 4. Build and sync the change

Run the project’s existing build command and resolve errors. Commit and push these changes to the branch linked to Lovable, then wait for them to sync and the preview to rebuild.

Open `/voiceflow-widget.js` on the preview host and confirm it returns JavaScript, then open the app. One launcher should appear and open. Complete the [visitor test](#test-conversation) before publishing.

<a id="configure-widget"></a>

## Configure appearance and sessions

Keep guest support separate from the application’s account state.

Choose your launcher, colors and icon in Voiceflow’s **Widget** panel, then [publish the changes](/docs/documentation/deploy/environments/publishing). If installation details change, replace the generated body in `public/voiceflow-widget.js` and release a new app version.

| App event | What to check |
| --- | --- |
| First page load | The app renders successfully, then one widget launcher appears. |
| Client-side navigation | The existing widget stays usable; another loader is not appended. |
| Reload or return visit | Retention follows the [widget persistence settings](/docs/documentation/deploy/widget/web-chat-api#configuring-chat-persistence). |

The app’s login does not automatically authenticate widget users. A browser-supplied user ID cannot authorize access to private records. Add backend authorization before implementing protected account actions. Page-specific or account-scoped support also needs an explicit widget lifecycle; this recipe is site-wide public support.

<a id="test-conversation"></a>

## Test a visitor conversation

Verify the supplied widget through the app’s actual browser flow.

### 1. Open a fresh preview

Use Lovable’s preview **Open in new tab** control. Open a page directly and reload it. Confirm that the app renders without a server-rendering error and one launcher appears and opens. Preview access may require your Lovable login; this does not authenticate a customer to Voiceflow.

### 2. Ask a question and follow-up

Ask a prepared question, such as “What is your refund policy?” Then ask “How do I request a refund?” Both replies should match the content in your agent’s Knowledge.

### 3. Check the project and navigation

Find the exchange in [Transcripts](/docs/documentation/measure/transcripts) to confirm the intended project. Follow an app link, send another message and reload. Check retention and duplicate launchers. Repeat with relevant consent choices if the app uses consent controls.

<a id="troubleshooting" />

### Server rendering fails

Move browser work into the client-side effect.

Remove widget execution and browser-global access from module scope or server-rendered code. Keep the component’s DOM work inside its effect. In Studio, ask Lovable to fix the failing route and show a successful build before retesting.

### The widget does not appear

Check the public asset and the generated loader.

Inspect Network for `/voiceflow-widget.js` and `cdn.voiceflow.com`. The public file must return JavaScript, not a 404 or the app’s fallback HTML, and must contain the generated script body without HTML tags. Review initialization errors, domain restrictions and consent rules with the project owner. Reload after correcting a failed load.

### Navigation creates another widget

Check the root mount and other installations.

Keep one root component and its script-ID guard. Remove older widget copies from HTML, page components or other integrations. Do not initialize the widget in a route-change callback. Reload after removing duplicates and repeat the navigation test.

### The answer is wrong or missing

Check the installed project and published agent.

Compare the public script’s generated options with the Voiceflow project’s snippet. Confirm the intended release is published and retry with a fresh conversation. Correct missing policy information in Knowledge or instructions.

<a id="go-live"></a>

## Publish the reviewed app

Release the Lovable installation separately from the Voiceflow agent.

1. Have the Voiceflow owner publish the reviewed agent and widget settings.
2. In Lovable, choose **Publish**, review the destination and access settings, then **Publish** for a first release or **Publish changes** for an existing app.
3. Repeat the [visitor test](#test-conversation) on the published URL, using the audience access you configured.

Preview changes and synced commits do not update the published app by themselves. Lovable’s [publishing guide](https://docs.lovable.dev/features/publish) covers the release controls.

### Update or remove the widget

Maintain the generated script and persistent mount.

Publish agent and appearance changes in Voiceflow. For changed installation settings, update the public script, test and publish the app again.

To remove the widget, have Lovable or your developer remove the component’s root mount and its files, then publish the change. Check a fresh visitor window; an already-open document can retain its loaded widget until reloaded.

<a id="custom-interface"></a>

## Custom interface guides

Planned Lovable walkthroughs for your own conversation UI.

Custom chat and voice walkthroughs are **coming soon**, separately from this widget guide.

| Planned guide | API reference |
| --- | --- |
| Add custom chat | [Chat agents](/docs/api-reference/agent-runtime/chat) |
| Add custom voice | [Voice agents](/docs/api-reference/agent-runtime/voice) |
