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.
Building your own interface? Custom chat and voice walkthroughs are coming soon. Start with Chat agents or Voice agents for the APIs.
New to Voiceflow? Build a support 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.
Before you begin
Prepare the agent and access to the Lovable project you will update.
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.
Install the widget
Load the generated script from a persistent client-side component.
Studio
Copy your installation snippet
In Agent studio, open Widget → Installation and copy the complete generated snippet, including its script tags.
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:
Paste your snippet after the request before sending. Build mode makes the changes; Chat and Plan modes do not implement this request by themselves.
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. 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. Work from its current synced branch; do not create another Lovable project or replace the app’s framework.
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.
Create the client-side component
Create src/components/VoiceflowWidget.tsx:
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.
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:
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.
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 before publishing.
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. If installation details change, replace the generated body in public/voiceflow-widget.js and release a new app version.
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.
Test a visitor conversation
Verify the supplied widget through the app’s actual browser flow.
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.
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.
Check the project and navigation
Find the exchange in 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.
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
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.
Publish the reviewed app
Release the Lovable installation separately from the Voiceflow agent.
- Have the Voiceflow owner publish the reviewed agent and widget settings.
- In Lovable, choose Publish, review the destination and access settings, then Publish for a first release or Publish changes for an existing app.
- Repeat the visitor test 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 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.
Custom interface guides
Planned Lovable walkthroughs for your own conversation UI.
Custom chat and voice walkthroughs are coming soon, separately from this widget guide.