> ## 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 Laravel

> Install the supplied Voiceflow chat widget in Laravel, handle browser navigation and cleanup, and test a visitor conversation.

## Overview

Install the supplied embedded text-chat widget in a Laravel Blade layout. This starter also uses Livewire 4 navigation: a browser custom element owns the panel as page bodies are replaced. This recipe installs an embedded panel for public support using an existing Voiceflow agent.

**Note:** 

**Building your own interface?** Framework-specific custom chat and voice guides are [planned](#custom-interface). Use [Chat agents](/docs/api-reference/agent-runtime/chat) and [Voice agents](/docs/api-reference/agent-runtime/voice) for their separate API contracts.

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

## Before you begin

Prepare the published public agent and framework access.

| Requirement | What to prepare |
| --- | --- |
| Framework scope | Laravel 13.43.0 / Livewire 4.4.8 / PHP 8.6.0. The supplied starter targets the rendering model described above. |
| Agent owner | A [published support agent](/docs/guides/usecases/customer-service/build-faq-agent), its public widget project ID and the intended [Environment alias](/docs/documentation/deploy/environments/overview#aliases). |
| Widget configuration | Public API access already enabled; a Published release in that Environment. Disable file uploads in its published widget settings for this text-only recipe. |
| Site developer | Docker for the complete starter; PHP 8.6 and Composer for native adaptation; permission to edit and deploy the site and a staging origin. |
| Visitor test | A known question and expected answer, plus access to the resulting [Transcript](/docs/documentation/measure/transcripts). |

Obtain the project ID, alias and expected answer from the agent owner before editing the files. This starter uses the **public `verify.projectID` contract**; client-key, private/prototype and Private Cloud configurations require their own compatible installation. Keep framework application secrets, website login tokens and personal/service API keys on the server. See [Blade layouts](https://laravel.com/docs/13.x/blade) and [Livewire navigation](https://livewire.laravel.com/docs/4.x/navigate) for the platform behavior.

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

## Install the widget

Configure and activate one browser-owned chat panel.

### 1. Download the complete starter

Download the [Laravel starter](/docs/examples/web-frameworks/laravel.zip) and extract it. It includes the entry files, dependency locks and `public/widget/widget.js`, `widget-config.js` and `widget.d.ts`. The helper loads the supplied widget from its CDN; no Voiceflow npm package is needed.

For an existing site, copy only the widget integration and merge the placement below into your existing layout. Keep its other configuration. Remove any earlier Voiceflow snippet: this global widget API supports one active widget per document.

### 2. Choose the public project and Published release

Edit `public/widget/widget-config.js`:

```javascript
// Public identifiers for an existing public widget project, not API credentials.
export const widgetOptions = {
  verify: { projectID: "YOUR_PROJECT_ID" },
  url: "https://general-runtime.voiceflow.com",
  environmentID: "YOUR_ENVIRONMENT_ALIAS",
  versionVariant: "published",
  autostart: true,
  allowDangerousHTML: false,
  assistant: {
    type: "chat",
    persistence: "memory",
    enableVoiceInput: false,
    enableVoiceOutput: false,
    enableVoiceMode: false,
  },
};
```

Replace both `YOUR_` values with the supplied project ID and Environment alias. `environmentID` and `versionVariant: 'published'` select that Environment’s Published release; [legacy `versionID` compatibility](/docs/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads) is separate. Raw HTML is disabled while ordinary Markdown remains available.

### 3. Add the browser integration

Copy the widget files to `public/widget/`. Add the support element and module script once to the shared Blade layout. The example keeps the support subtree under `wire:ignore`, and `data-navigate-once` prevents repeated module evaluation. Keep the existing Livewire assets in your layout.

`public/widget/widget-element.js`:

```javascript
import { mountWidget } from "./widget.js";

class VoiceflowSupport extends HTMLElement {
  stop = () => {};
  start = () => {
    this.stop();
    this.stop = mountWidget(this);
  };
  hidePage = () => this.stop();
  showPage = (event) => {
    if (event.persisted && this.isConnected) this.start();
  };
  connectedCallback() {
    this.replaceChildren(); // Cached HTML cannot restore a previous shadow root.
    this.start();
    window.addEventListener("pagehide", this.hidePage);
    window.addEventListener("pageshow", this.showPage);
  }
  disconnectedCallback() {
    this.stop();
    window.removeEventListener("pagehide", this.hidePage);
    window.removeEventListener("pageshow", this.showPage);
  }
}

if (!customElements.get("voiceflow-support")) {
  customElements.define("voiceflow-support", VoiceflowSupport);
}
```

`resources/views/layout.blade.php`:

```blade
<!doctype html>
<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>@yield('title', 'Support')</title>@livewireStyles</head>
<body>
<nav><a href="/" wire:navigate>Home</a> <a href="/about" wire:navigate>About</a></nav>
<main>@yield('content')</main>
<voiceflow-support wire:ignore></voiceflow-support>
<script type="module" src="{{ asset('widget/widget-element.js') }}" data-navigate-once></script>
@livewireScripts
</body></html>
```

### 4. Run the local installation

From the extracted folder, build and start the local fixture:

```bash
docker build -t voiceflow-laravel .
docker run --rm -p 127.0.0.1:5173:5173 voiceflow-laravel
```

Open `http://localhost:5173`. One embedded chat panel should replace the loading message. The installed panel proves browser startup; complete the [visitor test](#test-conversation) to verify answers from your actual agent.

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

## Handle widget lifetime and identity

Keep navigation, removal and guest conversations predictable.

Blade produces the HTML on the server; the browser module registers the custom element. Livewire navigation replaces body content without a full document reload. Removing the old support element invokes cleanup, and connecting the next element mounts a fresh panel. The element clears cached light-DOM children before mounting, because cached HTML does not contain its old shadow root.

The helper serializes `load()` and disposal, reuses its own downloaded loader, and creates a fresh inner HTMLElement for each mount. It calls `destroy()` only for the widget it owns, then removes that target. Keep the outer container’s children under widget ownership.

| Event | Required behavior |
| --- | --- |
| Owner remains through navigation | Retain the mounted conversation; do not load or launch again. |
| Owner is removed while loading | Cancel startup where possible; finish an already-started load before cleanup and another mount. |
| Refresh or real remount | `persistence: 'memory'` starts a fresh guest conversation. |
| Logout/account switch | Remove the previous owner before support returns for the next account. Revoke your application/backend session separately. |

Browser `userID`, page context and launch values do not authenticate a customer. This public widget supplies no private-record authorization. Protected operations require a trusted backend boundary on every read/write, turn and resume; use the [canonical trusted-customer guidance](/docs/guides/integrations/crms/recognize-returning-customers#recognize-the-customer) before adding them. Widget `destroy()` does not delete transcripts or undo an in-flight business action.

### Use Blade without Livewire

Keep the adaptation separate from the supplied starter.

Keep the custom support element and module script, and remove the `wire:navigate`, `wire:ignore` and `data-navigate-once` attributes plus the Livewire directives when your application does not install Livewire. Ordinary links load new documents. The browser element still handles removal and browser-cache restoration; no Livewire hook is required for a full page load.

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

## Test a visitor conversation

Verify the installed widget, replies and framework navigation.

Use a staging deployment with the final project/release configuration. If approved-domain restrictions are enabled, have the agent owner allow that origin. Check that the site’s content security policy permits the widget’s script, styles, fonts and runtime connections.

### 1. Open as a visitor

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

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

Send the prepared support question and a related follow-up. Both replies must match the intended agent/release and preserve the expected conversation context. Locate this exchange in the intended project’s [Transcripts](/docs/documentation/measure/transcripts).

### 3. Navigate and return

Use the starter’s **About** link and Back. Compare the result with [widget lifetime](#widget-lifecycle): a removed owner should clean up, then the next mount should show a fresh conversation. Open the nested route directly too. Check that navigation never leaves two active panels or a blank cached copy.

### 4. Check slow startup and recovery

Leave while the CDN/setup is pending, then return. There must be no overlapping load or detached-target error. Interrupt and restore the network. If a business action’s result is uncertain, check its outcome before retrying. Reload to confirm the fresh-start policy. If the site has sign-in, remove the widget during logout/account change and confirm that old messages do not return for another account.

### The panel stays blank

Trace the browser entry and configuration before changing the agent.

Confirm both placeholders were replaced and that the documented module/component actually executes in the browser. Check missing static files, blocked CDN/style/font/runtime requests, project public access, the Environment alias, its Published release and approved origins. The helper gives the target a visible height. After repairing a failed or partial load, reload the document; it does not automatically retry the SDK.

### Navigation duplicates or restarts support

Check layout placement, caching and cleanup ownership.

Remove other snippets and keep one owner. Compare your installation with the local [lifecycle instructions](#widget-lifecycle), including any framework cache or DOM-replacement behavior. A real unmount intentionally starts fresh with memory persistence. Preserve the helper’s cleanup rather than calling `load()` after every route event.

### The wrong agent answers

Check the published route with a fresh conversation.

Compare the installed project ID and Environment alias with the agent owner’s values. Confirm the known answer exists in that Published release; editing Draft does not change it. Use [Environment publishing](/docs/documentation/deploy/environments/publishing) before retesting.

<a id="release"></a>

## Release and maintain the installation

Publish the agent and website independently, then test production.

### 1. Publish the agent and deploy the application

Have the agent owner [publish the reviewed Environment](/docs/documentation/deploy/environments/publishing), including widget-setting changes. Use the existing Laravel production host with the document root set to `public/`. Install the locked production dependencies with `composer install --no-dev --optimize-autoloader`, publish the widget files, and retain your application’s production configuration. Set `APP_ENV=production`, `APP_DEBUG=false` and a persistent server-only `APP_KEY`; refresh Laravel configuration/view caches through your normal release process. The Docker command below is a local demonstration server.

### 2. Accept the production route

Open the actual HTTPS production URL and repeat the [visitor test](#test-conversation), including a direct nested-route request. Agent publication and site deployment are separate releases. Record the application commit, Environment release and observed widget version.

### Update, roll back or remove

Change the responsible release and repeat the visitor test.

Keep the last working application build and public widget configuration. The CDN URL moves independently of the framework lockfile, so test after widget updates. App rollback does not roll back the agent or delete transcripts. To remove support, remove its entry/component and deploy, retaining cleanup during removal. After any change, use the same visitor test.

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

## Custom interface guides

Planned framework guides for your own chat or voice UI.

Custom-interface walkthroughs for Laravel are **planned**, separate from the completed supplied-widget procedure.

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