Skip to main content

Drupal Chatbot Module

Use the official ChattyBox Drupal module when you want a Composer-managed installation for a Drupal 10 or Drupal 11 site. The locally audited 0.1.0 module attaches its hosted widget loader on eligible non-admin requests whose Drupal request format is HTML, and uses a hard-coded API endpoint. 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 chatbot. Under Install → Keys & domains, inspect or create a public widget key and check its origin settings. Under Install → Website installation, select a suitable key and copy its data-api-key value from the installation snippet.

Composer Installation​

This installation uses the public GitHub repository as a Composer VCS source. Add the repository declaration below before running composer require; verify current package availability and tags before installing.

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; the module declares PHP 8.1 as its minimum, although your Drupal version may require newer PHP. Standard Drupal Composer installer paths often place it under web/modules/contrib/, but project mappings can differ. ^0.1 is a version constraint, not an exact pin: Composer resolves and locks a version. Use an exact version when reproducibility is required.

Review the public Drupal module source and tagged changes before upgrading; confirm the available update mechanism for your installation.

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 website installation snippet.
  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. A supported override takes priority only if the project allows script overrides. In current-source hosted widget v16, auto mode tries page language, browser languages, then the configured default, skipping unsupported values and finally falling back to English; fixed mode uses the supported project default or English. Verify the deployed loader before relying on this separately versioned behavior.
  6. Enable the chatbot and save the configuration.

On admin routes or requests whose Drupal request format is not HTML, the audited module does not attach the widget loader. It does not inspect the final response Content-Type or determine whether frontend content is private. For eligible requests, it attaches the public key, hard-coded 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 hard-coded in the audited module version, not discovered from the key or automatically updated. Changing the loader URL does not change that endpoint. Compare it with your website installation snippet; if the snippet uses another API deployment, use its manual widget integration without the module. Remote script URLs must use HTTPS (HTTP is permitted only for local development hosts).

Keys created without restrictions work across browser origins; a key prepared for a website can already be restricted to that site's origin. Optional restrictions under Install → Keys & domains require each intended scheme, hostname, and port. A restricted key returns 401 Invalid API key for a missing or disallowed effective origin, taken from Origin or, if absent, the Referer origin. Origin restrictions are additional hardening, not visitor authentication.

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; the route name below is illustrative. The module does not add cache contexts or tags for the hook's decision. Implement and verify site-specific cache variation and invalidation for every condition, including both attachment and non-attachment cases, across Drupal and intermediary caches. An exclusion alone is not an access-control boundary.

/**
 * 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. The audited module skips insertion when it finds any marked script[data-chattybox-widget="true"]; it does not validate or reconfigure that script, and it does not detect unmarked scripts.

The module's automatic loader does not check consent before initializing. If consent is required before requests, use a consent-aware integration instead of enabling this automatic loader. On SPA route changes or consent revocation, prevent loading on excluded routes and actively tear down an initialized widget through an integration supported by the deployed loader; hiding it or removing only the script tag is insufficient. Reinitialize only when allowed. Teardown cannot undo requests already processed by the server.

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.