Drupal Chatbot Module

Use the official ChattyBox Drupal module when you want a Composer-managed installation for a Drupal 10 or Drupal 11 site. It loads the hosted widget on public HTML routes and keeps the production API endpoint configured automatically. This guide covers the operational setup. The Drupal AI chatbot module page covers the product at a glance and the evaluation workflow.

Before Installing

Complete the Getting Started flow first: connect your public Drupal URL, review indexed pages, and verify representative answers in Test Chat. Then create a browser-safe public key in Public Keys and copy it from the project Embed tab.

Composer Installation

The module is currently distributed as a tagged package in the public GitHub repository. It is not yet listed on Drupal.org or Packagist, so Composer needs the VCS repository declaration below before composer require can resolve it.

Add the public GitHub repository to the consuming Drupal project's root composer.json:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

If the project already has a repositories section, merge the chattybox-drupal entry into it. Then install the tagged module:

composer require openstaticfish/chattybox-drupal:^0.1

The package is declared as a drupal-module and requires Drupal ^10 || ^11. Standard Drupal Composer installer paths place it under web/modules/contrib/.

Review the public Drupal module source and tagged changes before upgrading. Directory-managed Drupal.org updates are not available yet.

To test the current development branch instead:

composer require openstaticfish/chattybox-drupal:dev-main

Enable and Configure

1. Enable ChattyBox from Extend, or run drush en chattybox.
2. Open Configuration > Web services > ChattyBox.
3. Paste only the public widget API key from the project Embed tab.
4. Leave the hosted widget script URL unless ChattyBox has provided a preview or self-hosted loader URL.
5. Leave the language override blank to follow the project's locale policy, or enter a supported lowercase code such as en, fr, or de. In auto mode, page language wins over browser language; fixed mode uses the project's default. An override takes effect only if the project allows script overrides.
6. Enable the chatbot and save the configuration.

The module does not load on administrative routes or non-HTML responses. It adds the public key, managed production endpoint, optional locale, and widget loader through Drupal's declared library and drupalSettings.

Fresh installs start disabled, with an empty key and locale override. The settings form is at /admin/config/services/chattybox and requires the administer chattybox configuration permission. The module loads the widget; it does not crawl or synchronize Drupal content.

The API endpoint is built into the module, not discovered from the key. Changing the loader URL does not change that endpoint. If your Embed snippet uses another API deployment, use its manual widget snippet without the module. Remote script URLs must use HTTPS (HTTP is permitted only for local development hosts).

Public keys work across browser origins by default. If you enable an origin restriction in Public Keys > Edit origins, list each intended scheme, hostname, and port. Missing or disallowed request origins return 401 Invalid API key.

Exclude Additional Routes

The module skips administrative routes automatically. A custom module can disable the widget on additional public routes with hook_chattybox_load_widget_alter():

Administrative-route checks are not a privacy check on all frontend content. Add exclusions for checkout, account, and membership routes where appropriate.

/**
 * Implements hook_chattybox_load_widget_alter().
 */
function mymodule_chattybox_load_widget_alter(&$should_load, $config, $route_match) {
  if ('commerce_checkout.form' === $route_match->getRouteName()) {
    $should_load = FALSE;
  }
}

Manual Fallback

Composer is the recommended installation path. If your Drupal deployment cannot use Composer, copy the module into web/modules/custom/chattybox or another custom module directory, enable it, and configure it from Configuration > Web services > ChattyBox.

Do not paste a management credential into the module. The public widget API key is intended for frontend markup.

Choose one loader: do not enable the module alongside a theme snippet, GTM tag, or SDK mount. Its browser behavior reuses an existing marked script without changing that script's configuration.

Verification

After configuring the module:

• Open a public Drupal page in an incognito window.
• Confirm the widget launcher appears once.
• Ask a real visitor question.
• Verify a supported answer cites indexed public Drupal pages and an unsupported question shows the fallback, which can have no sources.
• Check the browser console for missing data-api-key, data-api-url, or key errors.
• Test both excluded and included routes, with Drupal/page/CDN caches warmed as well as cold. Rebuild relevant caches after settings or hook changes. A server-side route exclusion does not tear down a widget already loaded during client-side navigation.

Continue with the launch checklist before announcing the chatbot.