Overview

Add Voiceflow’s floating chat widget to Drupal 10 or 11 so visitors can ask your AI agent about your products, policies or services. This developer guide installs a site-owned module that loads the widget on non-administrative pages and stays separate from your theme.

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 Drupal accounts or private records.

Before you begin

Prepare the agent, module deployment access and a test site.

In Voiceflow, open Widget → Modality & interface. Set Modality to Chat and Chat interface to Widget, then publish. Review staging and production hosts if the project restricts widget domains.

Have the Voiceflow owner supply the complete snippet if you do not manage the agent. Keep personal and service API keys out of browser code.

Install the widget

Package the generated loader as one Drupal asset library.

1

Create the module files

In a Composer-based project, create web/modules/custom/voiceflow_widget/. Replace web/ with your document root if it differs.

Create voiceflow_widget.info.yml:

Create voiceflow_widget.libraries.yml:

Create voiceflow_widget.module:

The module attaches its library to ordinary pages. The cache context preserves the administrative-page distinction in cached output. Drupal’s asset-library guide explains the registration and attachment model.

2

Add the generated JavaScript

Create js/voiceflow-widget.js inside the module:

Replace the comment with the JavaScript between the opening <script ...> and closing </script> tags in your generated Widget → Installation snippet. Preserve that body unchanged, including its authorization, loader, runtime URLs and environment settings. Do not put HTML tags in this .js file.

Drupal loads this library in the page footer. The guard prevents another initialization if the file executes again. Do not also place the loader in a Drupal behavior that runs after every AJAX update.

3

Enable and rebuild caches

Deploy the module files to staging. From the Drupal project root, run:

If the site does not use Drush, have its administrator enable Site Voiceflow Widget under Extend, then clear caches under Configuration → Development → Performance.

Open a public page as a logged-out visitor. Its source should include the module’s js/voiceflow-widget.js asset and the launcher should appear. Administrative pages should omit it. Continue with the visitor test.

Do not edit Drupal core or your theme’s templates for this installation. Keep the module as the site’s only Voiceflow loader.

Configure appearance and placement

Keep widget settings separate from Drupal’s attachment and cache rules.

Choose the launcher, colors and icon in Voiceflow’s Widget panel, then publish the changes. If installation details change, replace the generated body in the module’s JavaScript file, increment the library version and rebuild caches.

For narrower placement, have the Drupal developer change the attachment condition and declare the corresponding cache contexts. Test both included and excluded URLs with cold and warm caches. A visibility rule that works only with caching disabled is not ready to release.

A Drupal login or browser-provided user ID does not authorize private agent actions. Keep protected record access behind backend authorization. If your site’s consent manager gates functional widgets, connect initialization to its existing consent flow before enabling that behavior.

Test a visitor conversation

Verify a useful answer through the widget on the staged Drupal site.

1

Open a public page

Use a private browser window. Confirm that one launcher appears and opens. Reload the page to check the cached response too; do not rely only on an administrator’s session.

2

Ask a question and follow-up

Ask a prepared question, such as “What services does your team offer?” Then ask “How do I contact the team?” Both replies should match the content in your agent’s Knowledge.

3

Check the project and page behavior

Find the exchange in Transcripts to confirm the intended project. Visit another public page and test a relevant AJAX interaction. Check retention and duplicate launchers. Verify the module’s asset is absent on an administrative route. Test relevant consent choices if you added consent gating.

The module is not listed

Check its location and metadata.

Confirm the folder is under the active site’s custom modules directory and that the file is named voiceflow_widget.info.yml. Check YAML indentation, supported core versions and the deployment target, then rebuild caches.

The asset or launcher is missing

Check activation, the generated body and cached output.

Confirm the module is enabled and the browser receives js/voiceflow-widget.js. Check the guard’s comment was replaced with the generated JavaScript body. Rebuild Drupal caches; inspect Console and Network for syntax errors, blocked cdn.voiceflow.com requests or rejected setup. Review relevant domain and consent restrictions with the project owner.

AJAX creates duplicate widgets

Check behaviors and other installations.

Keep the generated loader in this one guarded library. Remove copies from behaviors, blocks, theme scripts or tag managers, then rebuild caches and reload. Test the AJAX interaction again.

The answer is wrong or missing

Check the project, release and script version.

Compare the installed generated options with the current Voiceflow snippet. Confirm the intended release is published and retry with a fresh conversation. If the browser receives an older script, increment the library version and rebuild caches. Correct missing service information in Knowledge or instructions.

Release the Drupal module

Deploy the reviewed site installation separately from the agent.

  1. Have the Voiceflow owner publish the reviewed agent and widget settings.
  2. Deploy and enable the module on production with that project’s generated script body. Rebuild Drupal caches and any relevant page/CDN cache.
  3. Repeat the visitor test on the production URL.

Update or remove the widget

Maintain the module and its asset version.

Publish later agent and appearance changes in Voiceflow. When installation settings change, update the generated body, bump the library version, deploy and rebuild caches.

To remove the installation, uninstall Site Voiceflow Widget under Extend → Uninstall, or run vendor/bin/drush pm:uninstall voiceflow_widget -y, then rebuild caches. Check a fresh visitor window before removing the unused module files. Keep unrelated modules and theme code intact.

Custom interface guides

Planned Drupal walkthroughs for your own conversation UI.

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

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