Add a chatbot to MuseDock CMS

A chatbot or chat widget is installed on your site by pasting a small snippet of code supplied by the provider. In MuseDock CMS you do not need to edit the theme or any file: the settings have a custom code field that loads it on every public page. This guide explains how to use it, what to paste, how to check it works and what to do if it does not show up. It applies to any chat provider (AI assistants, customer-support chats, WhatsApp widgets…), because they all work the same way: a <script> loaded from their server.

Before you start

• Administrator access to your site in MuseDock CMS.
• The install snippet given by the chatbot provider. It is usually called "embed code" or "widget script", and it is normally one or two lines.
• Know where it goes: this method installs the chat on all public pages of the site (you cannot pick page by page with this field).

Step by step

1. Sign in to your site's administration.
2. Go to Settings → General and scroll down to the Custom code card.
3. In the Code at the end of <body> field, paste the provider's snippet exactly as given.
4. Click Save changes.
5. Go to Settings → Security (CSP) and allow the chat's domain. Without this step the browser will block the script and nothing will show. It is explained in the section Allow the chat's domain (CSP).
6. Open a public page of your site in a private browser window and check that the chat button or window appears (usually a floating bubble at the bottom right).

What to paste (and what not to)

Providers usually give you an instructions page with several sections. Paste only the embed snippet, the one that looks like this:

<div
  id="chatbot"
  data-bot-id="YOUR_BOT_ID"
  data-auto-open="false">
</div>
<script src="https://chat.example.com/bot/YOUR_BOT_ID/script.js" defer></script>

Names, attributes and address vary by provider; always copy theirs. Do not paste into that field:

• CSP (Content-Security-Policy) instructions, or nginx, Apache or other server examples. They are not page code: in MuseDock CMS the CSP is managed in Settings → Security (CSP), as explained below.
• JavaScript event examples (opening the chat from a button, sending user data…) unless you really need them. They are optional.
• Explanatory text, provider comments or private keys. A website chatbot only needs the bot's public identifier. If the provider gives you a secret key or API key, that never goes on the web page.

Where to paste it: the three fields

Field	When to use it
Code in <head>	Meta tags, Search Console verification, external styles and fonts.
Code at the start of <body>	Tag managers (the noscript part of Google Tag Manager) and scripts that must load first.
Code at the end of <body>	Chatbots, widgets, tracking pixels. This is the right place for a chat: it loads after the content and does not slow the page down.

Allow the chat's domain (CSP)

Your site sends browsers a Content Security Policy (CSP): the list of domains the page may load scripts from, connect to or show content from. It is a protection against malicious code and is on by default. If your chatbot's domain is not on that list, the browser blocks the script even though you pasted it correctly and the chat does not appear. In the browser console (F12) you will see an error like this (the exact text varies by browser):

Loading the script 'https://chat.example.com/bot/YOUR_BOT_ID/script.js' violates the following
Content Security Policy directive: "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net …".
Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback.
The action has been blocked.

The fix is to allow the chat's domain. You do not need to touch the server or the theme: the CMS has a section for it.

1. Go to Settings → Security (CSP). You need permission to edit settings.
2. Fill in the lists the chat needs (one address per line, with https:// or wss://, no trailing slash or path). For a provider at chat.example.com:

List	When it is needed	What to enter (example)
Scripts (script-src)	Always: it is the domain of the <script src="…"> you pasted.	https://chat.example.com
Connections (connect-src)	Almost always: the chat sends and receives messages over AJAX/fetch or WebSocket.	https://chat.example.com wss://chat.example.com
Frames (frame-src)	Only if the chat is shown inside an iframe (the console names frame-src).	https://chat.example.com
Images (img-src)	Usually not: by default images from any https address are allowed. Only if the console names img-src.	https://chat.example.com

3. Save. The domains you add are added to those the CMS already allows; they do not replace them.
4. Reload the public page with Ctrl+F5 (or in a private window). If it still does not change, wait a few minutes because of the cache.

How to find out what is missing: open the console (F12) and reload. Each block names the directive (script-src, connect-src, frame-src, img-src) and the domain. Add that domain to the matching list and repeat until no CSP errors remain. If the provider uses several domains (one for the script, another for the API, another for real-time messages), all of them must be allowed. Subdomain wildcards are accepted, for example https://*.example.com.

Form rules: only addresses starting with https://, http://, wss:// or ws:// are accepted; lines in any other format are dropped on save without a warning, so check your domain is still there after saving.

Security: add only trusted domains controlled by your provider. Each allowed domain can load code and content on all your pages. Allow only what the console asks for, and avoid broad wildcards when a specific domain is enough.

Check that it works

1. Visually: open the site in a private window. The chat button should be visible.
2. Page source: right-click and choose "View page source", then search for the provider's script address. If it is there, the CMS is printing it.
3. Browser tools (F12): the Network tab should show the script loading with status 200, and the Console tab should show no red errors from the chat.

Caching

MuseDock CMS keeps a copy of your pages to serve them faster to anonymous visitors. After changing the custom code, the old copy may keep showing for a while without the chat. If you just saved it and cannot see it:

• Reload with Ctrl+F5 (or test in a private window).
• Wait a few minutes and look again.
• If you use Cloudflare or another CDN that caches HTML, purge the page's cache.

Privacy and cookies

A chatbot loads third-party code and almost always stores a conversation identifier in the visitor's browser and sends their messages to the provider's server. That has legal consequences if your site is visited from the European Union:

• Mention it in your privacy and cookie policies: that you use a chat, who the provider is and why the data is processed.
• Check whether the provider uses non-essential cookies or storage: if so, the usual approach is to load the chat only after the visitor accepts. Ask your provider how; many offer a "load after consent" option or a function to start the chat on demand.
• Avoid collecting sensitive data in the chat, and tell visitors when they are talking to an AI.

Security: paste trusted code only

Whatever you paste into these fields runs on all your public pages with the same permissions as your own site. A malicious script could read what your visitors type or redirect them. So:

• Copy the snippet directly from the provider's dashboard, never from an email or message you were not expecting.
• Check the script address belongs to the provider's official domain and starts with https://.
• If someone else administers your site, let them know: anyone with access to Settings can change this field.

If your theme does not show the custom code

The CMS stores the three fields, but it is the theme template that prints them, and not every theme does. If the chat does not show even after saving and checking the cache (and the page source does not contain the script), ask whoever maintains the theme to add these lines just before </body> in the main layout:

{{-- Site custom code before </body> --}}
@php $_customBodyEndCode = site_setting('custom_body_end_code', ''); @endphp
@if(!empty($_customBodyEndCode))
{!! $_customBodyEndCode !!}
@endif

Likewise custom_head_code inside <head> and custom_body_start_code right after the opening <body>.

How to remove it

Go back to Settings → General → Custom code, delete the snippet from the Code at the end of <body> field and save. Within a few minutes (the cache time) the chat disappears. If you only want to turn it off temporarily, keep the code in a separate document before deleting it.

Troubleshooting

Symptom	Likely cause	What to do
Nothing appears after saving	Page cache.	Private window, Ctrl+F5, wait a few minutes or purge the CDN cache.
The page source does not contain the script	The theme does not print the field, or it was saved in another field.	Confirm it is in "Code at the end of <body>" and read the previous section.
The script is there but there is no bubble	Wrong bot identifier, unpublished bot, or your domain is not allowed at the provider.	Check in the provider's dashboard that the bot is active and your domain is in its allowed-sites list.
"Violates the following Content Security Policy directive" in the console	The chat's domain is not allowed in the site's CSP.	Allow it in Settings → Security (CSP), in the list the error names (scripts, connections, frames or images). See the previous section. If your server or CDN also adds its own CSP, it must allow it too.
The chat loads but does not send or receive messages	Connections (connect-src) are not allowed, for example the wss:// WebSocket.	Add the provider's https:// and wss:// addresses under "Connections".
Shows on some pages but not others	Old cache on those pages, or that page does not use the main layout.	Purge the cache; if it persists, check that the template includes the site footer.
Not showing on mobile	The provider has a "hide on mobile" option on.	Check the matching attribute in the snippet and in the provider's dashboard.
Missing in some browsers or with extensions	An ad or tracker blocker.	Try a private window without extensions. You cannot control this on the visitor's device.
The page goes blank or breaks	Something that was not embed code was pasted (instruction text, an unclosed tag).	Empty the field, save and paste only the embed snippet.

Frequently asked questions

Can I show the chatbot on only some pages?

Not with this field: it loads on all public pages. If you need it on a single page, some providers let you restrict by address from their own dashboard.

Do I need to install a plugin?

No. The custom code field is built into the CMS.

Does it work on a multilingual site?

The same snippet loads in every language. If your provider lets you set the chat language (for example with a data-lang attribute), see their documentation: the CMS does not change the snippet per language.

Does it affect site speed?

Very little, if the script sits at the end of <body> and uses defer or async, as in providers' examples. Avoid loading several chat widgets at once.

What if my provider gives me a different identifier from the one I expected?

Always use the one in the snippet the provider generated. Some systems distinguish between the agent or project identifier and the web bot or channel identifier; the one inserted on the web is the one in the embed code. If in doubt, confirm in their dashboard that this bot is linked to the right agent before publishing.

Can I use the same method for analytics or pixels?

Yes. Google Analytics, Search Console, Facebook Pixel, Hotjar and similar are pasted in the same fields, as the provider indicates (normally head for analytics and verification, and end of body for widgets).