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

> Add a Voiceflow AI agent to Drupal 10 or 11 with the supplied chat widget. Install a site-owned module, rebuild caches and test a visitor conversation.

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

**Note:** 

**Building your own interface?** Custom chat and voice walkthroughs are [coming soon](#custom-interface). Start with [Chat agents](/docs/api-reference/agent-runtime/chat) or [Voice agents](/docs/api-reference/agent-runtime/voice) for the APIs.

New to Voiceflow? [Build a support agent](/docs/guides/usecases/customer-service/build-faq-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.

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

## Before you begin

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

| Requirement | What to prepare |
| --- | --- |
| Voiceflow agent | A published agent, its complete **Widget → Installation** snippet and a known-answer question. |
| Drupal site | A supported Drupal 10 or 11 site, with a staging URL for review. |
| Developer access | Permission to deploy a custom module, enable it and rebuild caches. The commands below use the project’s installed Drush. |
| Site administrator | Someone who can verify public-page placement and any existing consent rules. |

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.

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

## 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`:

```yaml
name: 'Site Voiceflow Widget'
type: module
description: 'Loads the site’s Voiceflow chat widget.'
package: Custom
core_version_requirement: ^10 || ^11
```

Create `voiceflow_widget.libraries.yml`:

```yaml
widget:
  version: 1.0.0
  js:
    js/voiceflow-widget.js: { preprocess: false }
```

Create `voiceflow_widget.module`:

```php
<?php

/**
 * Implements hook_page_attachments().
 */
function voiceflow_widget_page_attachments(array &$attachments): void {
  $attachments['#cache']['contexts'][] = 'route.name';

  if (\Drupal::service('router.admin_context')->isAdminRoute()) {
    return;
  }

  $attachments['#attached']['library'][] = 'voiceflow_widget/widget';
}
```

The module attaches its library to ordinary pages. The cache context preserves the administrative-page distinction in cached output. Drupal’s [asset-library guide](https://www.drupal.org/docs/develop/creating-modules/adding-assets-css-js-to-a-drupal-module-via-librariesyml) explains the registration and attachment model.

### 2. Add the generated JavaScript

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

```javascript
(() => {
  if (window.__vfDrupalInstalled) return;
  window.__vfDrupalInstalled = true;

  /* PASTE_GENERATED_SCRIPT_BODY_HERE */
})();
```

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:

```bash
vendor/bin/drush en voiceflow_widget -y
vendor/bin/drush cr
```

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](#test-conversation).

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

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

## 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](/docs/documentation/deploy/environments/publishing). If installation details change, replace the generated body in the module’s JavaScript file, increment the library version and rebuild caches.

| Site behavior | What to check |
| --- | --- |
| Public or cached page | One widget loads, including for logged-out visitors. |
| Administrative route | The module’s asset is omitted. |
| AJAX update or navigation | The current document does not initialize a second widget. |
| Reload or return visit | Retention follows your [widget persistence settings](/docs/documentation/deploy/widget/web-chat-api#configuring-chat-persistence). |

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.

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

## 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](/docs/documentation/measure/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.

<a id="troubleshooting" />

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

<a id="go-live"></a>

## 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](#test-conversation) 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.

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

## Custom interface guides

Planned Drupal walkthroughs for your own conversation UI.

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

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