Embedding the Widget
How to add the Chatmancer chat widget to any website.
Embedding the Widget
The Chatmancer widget is a lightweight JavaScript bundle (under 100 KB gzipped) that renders a chat button and conversation panel in a shadow DOM on your page. It is fully isolated from your site's styles and will not interfere with existing CSS.
The embed snippet
After creating a chatbot, go to Settings → Embed to find your personalised snippet:
<script
src="https://your-cloudfront-url/widget.js"
data-chatbot-id="YOUR_CHATBOT_ID"
async
></script>Replace your-cloudfront-url with the CloudFront URL from your stack's Outputs tab, and YOUR_CHATBOT_ID with the ID shown in your dashboard.
Where to place it
Paste the snippet inside the <head> of every page where you want the chatbot to appear:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>My Website</title>
<!-- Chatmancer widget -->
<script
src="https://your-cloudfront-url/widget.js"
data-chatbot-id="YOUR_CHATBOT_ID"
async
></script>
</head>
<body>
...
</body>
</html>The async attribute ensures the widget loads without blocking your page render. If you prefer to place the script at the end of <body>, that works too — the widget initialises after the DOM is ready regardless.
Configuration attributes
Customise the widget's appearance and behaviour with data-* attributes on the script tag:
| Attribute | Type | Default | Description |
|---|---|---|---|
data-chatbot-id | string | required | Your chatbot's unique ID |
data-position | bottom-right | bottom-left | bottom-right | Where the chat button sits on screen |
data-primary-color | CSS hex colour | #6366f1 | Accent colour for the button and header |
data-text-color | CSS hex colour | #ffffff | Text colour inside the widget header |
Example with all attributes:
<script
src="https://your-cloudfront-url/widget.js"
data-chatbot-id="YOUR_CHATBOT_ID"
data-position="bottom-left"
data-primary-color="#0ea5e9"
data-text-color="#ffffff"
async
></script>You can also set these from the Appearance tab in your chatbot's dashboard settings — changes take effect immediately without updating your embed code.
Testing locally
The widget works on localhost. You do not need to deploy to a staging environment to test it. Simply run your site locally and add the snippet to your local HTML — the widget will connect to your live API endpoint.
Showing the widget only on certain pages
To restrict the widget to specific pages, wrap the snippet in a conditional:
<!-- Only show on /support and /contact pages -->
<script>
if (
window.location.pathname.startsWith('/support') ||
window.location.pathname.startsWith('/contact')
) {
const s = document.createElement('script');
s.src = 'https://your-cloudfront-url/widget.js';
s.setAttribute('data-chatbot-id', 'YOUR_CHATBOT_ID');
s.async = true;
document.head.appendChild(s);
}
</script>White-label and custom domain (Premium)
On the Premium and Whitelabel plans you can serve the widget from your own domain (e.g. chat.yourcompany.com) instead of the CloudFront URL. This removes any Chatmancer branding from the network requests visible in browser DevTools.
Setup involves pointing a CNAME at your CloudFront distribution and configuring an SSL certificate via AWS Certificate Manager. Contact us through the dashboard to get this set up.