WordPress Integration

Add the Maison concierge chat to your WordPress site in a few minutes — no coding experience required. You will copy two small code snippets into your theme file. WordPress official site ↗

Before you start

Administrator access to your WordPress site (yoursite.com/wp-admin)
Your Client UUID — find it in the Business Console under Settings

Recommended: Official WordPress Plugin

Maison provides an official WordPress plugin that handles script injection automatically. No code editing required — just install, enter your Client UUID, and the chat widget appears on every page.

1
Get the plugin
Clone the repository or download the zip from GitHub:
bash
```
git clone https://github.com/maison-labs/agent-inject-wordpressplugin.git
```
New to Git? See the GitHub cloning guide or download the zip directly from the repository page.
Install the plugin
In your WordPress admin, go to Plugins > Add New > Upload Plugin. Upload the maison-agent.zip file (found inside the cloned repo) and click Install Now, then Activate.
Configure your Client ID
Go to Settings > Maison Agent. Enter your Client ID (UUID from the Business Console). Optionally set Locale, Bottom Position, and Right Position (in pixels). Click Save Changes.
Verify
Visit your site. The Maison chat icon should appear at the configured position.

Alternative: Manual theme editing

If you prefer not to use the plugin, you can add the embed code directly to your theme files.

Log into your WordPress admin panel
Go to yoursite.com/wp-admin and sign in with your administrator account. You will land on the WordPress Dashboard.
Open the Theme File Editor
In the left sidebar, hover over Appearance and then click Theme File Editor. This opens a code editor for your active theme's files.
Select header.php
On the right side of the editor you will see a panel called Theme Files. Look for and click header.php. The file's contents will appear in the main editing area.
4
Paste the script tag before </head>
In the editor, use your keyboard shortcut (Ctrl+F or Cmd+F) to search for </head>. Click just before it and paste the following line on a new line above it.
html
```
<script src="https://agent.maison-labs.com/agent-inject.bundle.js" data-cfasync="false" data-no-minify="1" data-no-optimize="1" data-no-defer="1" data-noptimize="1"></script>
```

Paste the init script before </body>

Still in the same file, search for </body>. Paste the following snippet on a new line just above it. Replace YOUR_CLIENT_UUID with the UUID from your Business Console.

html

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

Click Update File
Scroll down in the editor and click the blue Update File button to save your changes.
Visit your site and verify
Open your website in a new browser tab. The Maison chat icon should appear in the bottom-right corner of the page. To confirm, open your browser DevTools (press F12), switch to the Elements tab, and look for #maison-chat-icon in the DOM.

Alternative: Insert Headers and Footers plugin

If the Theme File Editor is disabled by your hosting provider, install the free Insert Headers and Footers plugin from the WordPress plugin directory. Once activated, go to Settings > Insert Headers and Footers. Paste the script tag into the Scripts in Header box and paste the init script into the Scripts in Footer box. Click Save. The combined embed code for convenience:

html

<script src="https://agent.maison-labs.com/agent-inject.bundle.js" data-cfasync="false" data-no-minify="1" data-no-optimize="1" data-no-defer="1" data-noptimize="1"></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

Editing the wrong theme. Make sure the theme shown in the top-right of the Theme File Editor matches your currently active theme. If you have a child theme, edit header.php in the child theme, not the parent.

Forgetting to replace YOUR_CLIENT_UUID. The widget will not load without a valid Client UUID. Copy it exactly from your Business Console — it looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

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

Do not cache the Maison script

Maison ships widget updates through its own CDN. If a WordPress caching or minify plugin copies agent-inject.bundle.js into its own combined bundle, your site keeps serving that stale copy after Maison releases an update — and the widget can stop loading entirely. The loader tag above already carries exclusion attributes (data-cfasync, data-no-minify, data-no-optimize, data-no-defer, data-noptimize) that tell WP Rocket, LiteSpeed Cache, Autoptimize, and Cloudflare Rocket Loader to leave it alone — paste the tag exactly as shown and never remove these attributes.

Using a caching plugin? Also add agent-inject.bundle.js to your plugin's JavaScript exclusion list so it is never minified, combined, deferred, or cached: WP Rocket (File Optimization → Excluded JavaScript files), LiteSpeed Cache (Page Optimization → Tuning → JS Excludes), Autoptimize (JS, CSS & HTML → Exclude scripts), or W3 Total Cache (Performance → Minify → Never minify).

Troubleshooting: widget missing or outdated

If the chat widget stops appearing, or looks broken after a Maison update, a cached copy of an older loader script is the most common cause. Clear every cache layer, in this order:

Purge your WordPress cache
WP Rocket: Dashboard → WP Rocket → Clear Cache. LiteSpeed Cache: LiteSpeed → Purge All. Autoptimize: Settings → Autoptimize → Delete Cache. W3 Total Cache: Performance → Purge All Caches.
Purge your CDN cache
If Cloudflare, BunnyCDN, Fastly, or another CDN sits in front of your site, purge its cache too — a stale copy there survives a WordPress purge.
Hard-refresh and verify
Hard-refresh the page (Shift+Reload) and confirm the widget loads. In DevTools → Network, the script should load from agent-inject.bundle.js on Maison's CDN — not from a wp-content/cache/… path. If it still loads from the cache path, add the exclusion from the section above.

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