Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt
Use this file to discover all available pages before exploring further.
Embedding the widget places a chat bubble in the bottom-right corner of every page that loads the script. The bubble opens an iframe served by your Chatwoot instance — no additional server setup is required on the client’s website. When the voice agent is enabled for the inbox, the microphone button appears inside the widget automatically; no extra embed code is needed.
Get your embed snippet
Each inbox has a unique script. Fetch it directly from your dashboard so the websiteToken value is pre-filled.
Open inbox configuration
In the Chatwoot dashboard go to Settings → Inboxes, click the inbox you want to embed, then open the Configuration tab.
Copy the Messenger Script
Scroll to the Messenger Script section. Copy the full <script> block shown there. It contains your inbox’s websiteToken and the correct BASE_URL for your installation.
Paste the script into your site
Follow the framework-specific instructions below to add the script to every page.
The embed snippet
The script below is the universal template. Replace https://your-chatwoot-domain.com with your actual FRONTEND_URL and YOUR_WEBSITE_TOKEN with the token from the dashboard.
<script>
(function(d,t) {
var BASE_URL="https://your-chatwoot-domain.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.chatwootSDK.run({
websiteToken: 'YOUR_WEBSITE_TOKEN',
baseUrl: BASE_URL
})
}
})(document,"script");
</script>
BASE_URL must be your production HTTPS URL for the voice agent microphone button to work. Browsers block microphone access on non-HTTPS origins (except localhost). For local testing behind a tunnel, use ngrok, Cloudflare Tunnel, or your own domain.
Where to paste by framework
Paste the script block immediately before the closing </body> tag on every page.
- Plain HTML — add it to your shared footer template or directly in each
*.html file.
- WordPress — add it to
footer.php in your theme, or use a plugin such as Insert Headers and Footers to paste it into the footer.
- Shopify — open Online Store → Themes → Edit code and paste it into
theme.liquid just above </body>.
Plain React (Create React App)Paste the script into public/index.html before </body>.Next.js (App Router)Use next/script in your root layout:// app/layout.tsx
import Script from 'next/script';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Script
id="chatwoot"
strategy="afterInteractive"
dangerouslySetInnerHTML={{
__html: `(function(d,t) {
var BASE_URL="https://your-chatwoot-domain.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.async=true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.chatwootSDK.run({
websiteToken:'YOUR_WEBSITE_TOKEN',
baseUrl:BASE_URL
})
}
})(document,"script");`,
}}
/>
</body>
</html>
);
}
pages/_document.tsx inside <body>, or use next/script with strategy="afterInteractive" in pages/_app.tsx. Vue (Create Vue App)Paste the script into public/index.html before </body>.Nuxt 3Add it to nuxt.config.ts using the app.head.script option:// nuxt.config.ts
export default defineNuxtConfig({
app: {
head: {
script: [
{
innerHTML: `(function(d,t) {
var BASE_URL="https://your-chatwoot-domain.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.async=true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.chatwootSDK.run({
websiteToken:'YOUR_WEBSITE_TOKEN',
baseUrl:BASE_URL
})
}
})(document,"script");`,
type: 'text/javascript',
},
],
},
},
});
Paste the script into src/index.html immediately before the closing </body> tag:<!-- src/index.html -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>My App</title>
<base href="/" />
</head>
<body>
<app-root></app-root>
<script>
(function(d,t) {
var BASE_URL="https://your-chatwoot-domain.com";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.chatwootSDK.run({
websiteToken: 'YOUR_WEBSITE_TOKEN',
baseUrl: BASE_URL
})
}
})(document,"script");
</script>
</body>
</html>
After embedding
Once the script is on the page, the chat bubble appears in the bottom-right corner on the next page load. No restart or build step is required on the client’s website — the SDK loads asynchronously and does not block page rendering.
When the voice agent is enabled for the inbox (see Settings → Inboxes → Configuration → Voice Agent), a microphone button appears automatically next to the emoji button whenever the text input is empty. The widget re-fetches voice configuration every time the bubble is opened, so toggling the voice agent in the dashboard takes effect on the next bubble click without a page reload.
If the microphone button does not appear after enabling the voice agent, toggle the setting off, save, toggle it back on, save again, then close and reopen the chat bubble.