Drupal Integration

Add the Maison concierge chat to your Drupal site. The recommended approach is the official Drupal module — no code editing required. Supports Drupal 9.x, 10.x, and 11.x. Drupal official site ↗

Before you start

Administrator access to your Drupal site
SSH or Drush access (for module installation)
Your Client UUID — find it in the Business Console under Settings

Recommended: Official Drupal Module

Maison provides an official Drupal module that handles script injection and configuration through the Drupal admin interface. It injects the agent on every page automatically.

1
Get the module
Clone the repository or download the zip from GitHub:
bash
```
git clone https://github.com/maison-labs/maison-agent-drupal.git
```
New to Git? See the GitHub cloning guide or download the zip directly from the repository page.
2
Install the module
Copy the maison_agent directory into your Drupal installation at web/modules/custom/. Then enable and clear cache:
bash
```
drush en maison_agent
drush cr
```
Configure the module
Navigate to Configuration > Web services > Maison Agent Settings (or go directly to /admin/config/services/maison-agent). Enter your Client ID. Optionally set Locale and Icon Position (top, bottom, left, right in pixels). Click Save configuration.
Verify
Visit your site. The Maison chat icon should appear at the configured position. Open your browser DevTools (F12) and look for #maison-chat-icon in the DOM.

Alternative: Manual theme editing

If you prefer not to use the module, add the embed code directly to your theme's html.html.twig template, just before the closing </body> tag. Replace YOUR_CLIENT_UUID with your actual Client UUID.

html

<script src="https://agent.maison-labs.com/agent-inject.bundle.js"></script>
<script>
  function getQueryParam(param) {
    var queryString = window.location.search;
    var urlParams = new URLSearchParams(queryString);
    return urlParams.get(param);
  }
  var sessionId = getQueryParam('mcbsid');
  var mcbs = window.initMcbs({
    clientId: 'YOUR_CLIENT_UUID',
    sessionId: sessionId,
    // locale: 'en-US',                     // Override browser locale
    // iconPosition: { top: 0, bottom: 20, left: 0, right: 20 },  // Chat icon position (px)
    // onSessionUpdate: function(id) { console.log('Session:', id); },
    // onLocaleUpdate: function(locale) { console.log('Locale:', locale); },
  });
  mcbs.showIcon();
</script>

For the full list of configuration options, control methods, and callbacks, see the Widget SDK Reference.

Common mistakes

Module not in the correct directory. The maison_agent directory must be inside web/modules/custom/, not in the contrib directory. Adjust the path if your webroot differs.

Forgetting to clear cache. Always run drush cr after enabling the module or changing configuration. Drupal caches aggressively.

Forgetting to replace YOUR_CLIENT_UUID. The widget will not load without a valid Client UUID. Copy it exactly from your Business Console.

Using string values for iconPosition. Write bottom: 20, not bottom: '20px'. Values are plain numbers representing pixels — do not include units.

Not sure if it's set up correctly? Use the Site Diagnostic tool.