Overview

Install the supplied embedded text-chat widget in an Eleventy Nunjucks layout. Eleventy builds HTML and copies the browser files; the widget initializes only when a visitor opens a generated page. This recipe installs an embedded panel for public support using an existing Voiceflow agent.

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

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 Eleventy passthrough copy for the platform behavior.

Install the widget

Configure and activate one browser-owned chat panel.

1

Download the complete starter

Download the Eleventy starter and extract it. It includes the entry files, dependency locks and src/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 src/widget/widget-config.js:

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 is separate. Raw HTML is disabled while ordinary Markdown remains available.

3

Add the browser integration

Copy the widget files under src/widget/. Add passthrough copying from src/widget to widget, and put one support element plus its module script in the shared layout. The download includes the exact Eleventy config and two pages using that layout.

src/widget/widget-element.js:

src/_includes/layout.njk:

eleventy.config.js:

4

Run the local installation

From the extracted folder, install the pinned dependencies and start the app:

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

Handle widget lifetime and identity

Keep navigation, removal and guest conversations predictable.

The supplied site uses full document navigation. No browser router or framework hydration step owns the panel. The custom element creates a fresh embedded target on connection, cleans up on removal/pagehide, and handles browser-cache restoration. Passthrough copying is essential: a successful HTML build alone does not prove the widget files reached the output.

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.

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 before adding them. Widget destroy() does not delete transcripts or undo an in-flight business action.

Deploy under a path prefix

Keep the adaptation separate from the supplied starter.

The starter serves from /. For a subdirectory, configure Eleventy’s path prefix and apply its URL filter to the script path and internal links in the layout. Confirm the generated module URL resolves under the deployed prefix, including relative imports of widget.js and widget-config.js.

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.

3

Navigate and return

Use the starter’s About link and Back. Compare the result with widget lifetime: 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.

Check layout placement, caching and cleanup ownership.

Remove other snippets and keep one owner. Compare your installation with the local lifecycle instructions, 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 before retesting.

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, including widget-setting changes. Run npm run build and deploy _site/ to your static host. Confirm the output includes widget/widget-element.js, widget.js and widget-config.js, as well as the generated HTML. Use npm run start -- --port=5173 for a local server.

2

Accept the production route

Open the actual HTTPS production URL and repeat the visitor test, 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.

Custom interface guides

Planned framework guides for your own chat or voice UI.

Custom-interface walkthroughs for Eleventy are planned, 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.