Add the chat to a Drupal site

What it is

Drupal builds its pages through themes, and a theme can add things to the page head from its .theme file. The Agentency snippet for Drupal is a short PHP function that attaches the chat widget's script tag to every page's head. You paste it into your active theme's .theme file, replace the placeholder theme name with your real one, and rebuild the cache.

This is a developer-shaped task. If you would rather not edit a file, the alternative is any of the community modules that add a script to the head — paste the plain <script> tag into one of those instead, or put a link to your hosted chatbot page in your site's menu.

When you would use it

Use this for a Drupal 9, 10, or 11 site where you want live chat on every page. It is the route that does not require installing another contributed module, which matters on sites with a strict module review process.

Where to find it

Open Dashboard → Chatbots → your chatbot → Integrations → Plugins → Drupal.

Before you start

• You need file access to the theme and the ability to rebuild the cache, or someone who has.
• Work in your custom or sub-theme, not in a core theme such as Olivero. Core themes are replaced on update.
• Know your theme's machine name. It is the folder name of the theme and the prefix of the .theme file — this is what replaces THEME_NAME in the snippet.
• Add your site's domain to the widget allowlist. See Allow the widget on your domains.
• Confirm the chatbot is Active on its Playground tab.

Steps

1. Open Dashboard → Chatbots → your chatbot → Integrations → Plugins and click the Drupal card.
2. Click Copy theme code.
3. On the server, open your active theme's .theme file.
4. Paste the code at the end of the file.
5. Replace both occurrences of THEME_NAME with your theme's machine name. If your theme is acme_corp, the function becomes acme_corp_preprocess_html. Getting this wrong means the function never runs — Drupal matches it by name.
6. If your theme already has a preprocess_html function, do not add a second one. Move the body of the pasted function inside the existing one.
7. Save the file.
8. Rebuild the cache: drush cr, or in the admin at Configuration → Development → Performance → Clear all caches.
9. Open the site and send a test message. Confirm it lands in Conversations.

What the snippet looks like

The snippet builds a script element as a Drupal render array and attaches it to the head. Copy your own from the Plugins drawer — the token below is a placeholder:

<?php
// Add this to your Drupal theme's .theme file (replace THEME_NAME)
function THEME_NAME_preprocess_html(&$variables) {
  $chatbot_widget = [
    '#type' => 'html_tag',
    '#tag' => 'script',
    '#attributes' => [
      'src' => 'https://agentency.com/js/chatbot-widget.js',
      'defer' => TRUE,
      'data-widget-token' => 'wt_YOUR_WIDGET_TOKEN',
      'data-api-base-url' => 'https://api.agentency.com',
      'referrerpolicy' => 'strict-origin-when-cross-origin',
      'crossorigin' => 'anonymous',
    ],
  ];
  $variables['#attached']['html_head'][] = [$chatbot_widget, 'agentency_chatbot_widget'];
}
?>

The last argument, agentency_chatbot_widget, is the key Drupal uses to identify this head element. Leave it as it is: a unique key is what stops the tag being added twice.

If your team would rather ship this as part of a custom module than a theme, the same render array works from a module's hook_page_attachments().

What you will see

Nothing changes in the Drupal admin — this is a code change. After the cache rebuild, the chat bubble appears on every page of the site, for anonymous visitors and logged-in users alike, in the corner set by your chatbot's appearance settings.

Limits and plan notes

Embedding requires a paid Agentency plan. Free is hosted-link only — see Which plans include integrations and the pricing page.

The widget does not read Drupal content, users, or Commerce orders. To make the chatbot knowledgeable about your site, crawl it so its public pages become knowledge, or connect a Call action for live lookups.

If your site sends a Content Security Policy — common on Drupal sites in the public sector — the policy must permit the Agentency script and API host, or the browser blocks the widget before it starts.

Common problems

I cleared the cache and nothing appears.

The most likely cause is THEME_NAME not being replaced, or being replaced with the theme's human-readable name rather than its machine name. Check the folder name of the theme.

The site shows a PHP error after saving.

Your theme already had a preprocess_html function and now has two with the same name. Merge them into one.

It works for anonymous visitors but not when I am logged in.

Check whether an administration theme is active for your role — the head is coming from a different theme then. Apply the change to that theme too, or turn off the admin theme for front-end pages.

The tag appears twice in the page source.

The snippet is in both a base theme and a sub-theme, or in a theme and a module. Remove one.

Chat loads but is blocked.

The host in the visitor's address bar must be on the allowlist — including www, and each domain of a multisite install. See The widget is blocked.