Overview

Install the supplied embedded text-chat widget in a React component. React owns an empty container; an Effect starts Voiceflow after the browser commits it. This recipe answers public support questions using an existing Voiceflow agent; it installs an embedded chat panel rather than a floating launcher.

Building your own interface? Framework-specific custom chat and voice guides are planned. Use Chat agents and Voice agents for their separate API contracts.

Before you begin

Prepare the published public agent and application access.

The agent owner supplies the project ID, alias and expected answer before you configure the files. This example uses public verify.projectID; it does not convert generated client keys, private/prototype credentials or Private Cloud settings. For a different authorization format, use its supported installation contract. Keep personal/service API keys and website login tokens on your server. See React Effect lifecycle for the framework lifecycle.

Install the widget

Configure the example and mount one browser-owned chat panel.

1

Download the complete starter

Download React starter and extract it. It includes the required dependencies, entry files, src/widget/widget.js, widget-config.js and widget.d.ts. No Voiceflow npm package is required: the helper loads the hosted widget once.

For an existing application, copy the widget folder and adapt only the entry placement below. Remove any previous Voiceflow snippet before using this helper; the global widget API supports one active widget per document.

2

Set the public project and release

Edit src/widget/widget-config.js:

The example renders standard Markdown with raw HTML disabled. Replace both YOUR_ values. Use the Environment alias, not its display name. environmentID plus versionVariant: 'published' selects that Environment’s Published release. The legacy versionID option has separate compatibility behavior; do not substitute it here.

3

Place the widget in the application

Add VoiceflowChat once in the app shell, outside your router’s changing page outlet. The starter mounts it from src/main.jsx and includes a Toggle support button for the removal/remount check.

src/widget/VoiceflowChat.jsx:

src/main.jsx:

4

Run the installed page

From the extracted starter folder, install its pinned dependencies and start the development server:

Open http://localhost:5173. The loading message should be replaced by one chat panel. If support cannot load, inspect the console and the troubleshooting below. A rendered panel is the installation check; complete the visitor test to verify replies.

Handle widget lifetime and identity

Keep navigation, removal and guest conversations predictable.

The Effect returns synchronous cleanup. React Strict Mode can run setup, cleanup and setup again in development; the helper cancels a pending mount or waits for a started load before destroying it. It creates a fresh embedded target for the next mount.

The downloaded helper serializes load() and cleanup. It retains the loaded script, calls destroy() only for its own started widget, and removes that mount’s target. A new target avoids attaching a second shadow root to the same element. Keep the outer container empty so the framework and widget do not render the same children.

destroy() clears the rendered UI; it does not delete Voiceflow transcripts or undo an in-flight business action. Do not automatically replay an uncertain send after navigation or network loss.

Browser userID, page context and launch values do not authenticate a customer. This public widget installation supplies no access control for private records. Protected operations require authorization on every backend read/write and trusted identity on later turns and resumes; follow the canonical trusted-customer guidance before adding them.

Use server-rendered React

Adapt the placement while keeping one widget owner.

Keep browser access inside the Effect. This module can be imported during server rendering because the helper touches window only when mounted. In React Server Components, put the wrapper behind your framework’s client boundary; use the separate Next.js manual for its App Router setup.

Test a visitor conversation

Verify the installed widget, replies and framework lifecycle.

Use a staging deployment with the final project and Environment configuration. If approved-domain restrictions are enabled, have the agent owner allow the staging and production origins. Your content security policy must allow the widget script, styles, fonts and runtime connections; use the blocked request URL to diagnose a refusal.

1

Open as a visitor

Open the staging URL in a fresh browser session. Accept any configured notice. Confirm that one embedded chat panel appears and that input, keyboard and scrolling work at desktop and phone widths.

2

Ask the prepared question

Send the known support question and a related follow-up. Confirm both visible replies match the intended agent and retain the context needed for the follow-up. Locate this exchange in Transcripts for the expected project.

3

Check navigation and removal

Navigate through your app without replacing the shell. The existing chat should stay mounted. Use Toggle support off and on: the chat should restart once, without a second loader. Repeat with a slow connection, and leave while the loader is pending. Return to support: there must be no duplicate panel, detached-target error or second load overlapping the first. Check the network/console rather than counting the SDK’s unused overlay host as another chat panel.

4

Check recovery and account boundaries

Interrupt the network and restore it. Confirm the widget can continue or offers a clear recovery route; check an uncertain operation before retrying. Reload to verify the fresh-start policy. If your site has sign-in, remove the widget during logout/account change and confirm old messages are absent when support returns.

The support panel stays blank

Check the browser entry, configuration and blocked requests.

Confirm both placeholders were replaced, the module/asset paths resolve, and the component has a mounted browser container. The helper gives the embedded target a visible height. Inspect failed CDN, stylesheet, font and runtime requests, project public access, the Environment alias, its Published release and approved origins. Repair the cause, then reload the document; the helper does not retry a partially failed SDK load automatically.

Find a second owner or an unexpected component replacement.

Remove other snippets and mount the wrapper only once. Review keys, conditional rendering and page-versus-layout placement against widget lifetime. Keep the helper’s returned cleanup wired to the framework hook. Memory-only retention intentionally restarts after a real unmount or document reload.

The wrong agent or answer appears

Separate release selection from agent content.

Check the installed project ID and alias against the agent owner’s values, then test a fresh conversation. Confirm the expected answer exists in that Published release. Changing a draft does not update the selected release; use publishing before retesting.

Release and maintain the installation

Publish the agent and website independently, then test production.

1

Publish the agent and deploy the site

Have the agent owner publish the reviewed Environment, including widget-setting changes. Deploy dist/ after npm run build. Configure your host to serve index.html for application routes, while serving asset requests normally. Keep the public configuration in the browser bundle; store backend credentials separately.

2

Accept the production route

Open the actual HTTPS production URL and repeat the visitor conversation test, including a direct request to a nested route. Agent publication and website deployment are separate releases. Record the application commit, Environment release and observed widget version for rollback.

Update, roll back or remove

Change the responsible layer and verify the deployed route.

Keep the last working application build and configuration. The hosted widget URL is a moving release, so a framework lockfile does not pin its served bundle; regression-test after widget updates. An app rollback does not roll back the agent or delete transcripts. To remove support, remove the wrapper/HTML entry and deploy; keep its cleanup in place during removal. After any change, repeat the same visitor test.

Custom interface guides

Planned framework guides for your own chat or voice UI.

Custom-interface walkthroughs for React are planned. They are separate from the completed supplied-widget procedure.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.