Skip to main content
The Chatwoot website widget provides a customizable live chat interface for your website visitors. It supports real-time conversations, file attachments, and seamless handoff from AI to human agents.

​
Features

  • Real-time messaging - Instant two-way communication
  • File attachments - Share images, documents, and files
  • Customizable appearance - Match your brand colors and style
  • Pre-chat forms - Collect visitor information before starting chat
  • Business hours - Show availability and expected response times
  • Continuity via email - Continue conversations over email
  • HMAC verification - Secure user identity verification
  • Mobile responsive - Works seamlessly on all devices

​
Installation

1

Create a website inbox

Navigate to Settings → Inboxes → Add Inbox and select Website.Configure your inbox:
  • Website Name: Display name for your website
  • Website Domain: Your website URL (e.g., https://example.com)
  • Widget Color: Primary color for the widget (hex code)
2

Copy the installation code

After creating the inbox, you’ll receive a JavaScript snippet. Copy this code.
<script>
  (function(d,t) {
    var BASE_URL="https://app.chatwoot.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: 'YOUR_WEBSITE_TOKEN',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>
3

Add to your website

Paste the code before the closing </body> tag on every page where you want the widget to appear.
For single-page applications (SPAs) using React, Vue, or Angular, see the Widget SDK documentation for framework-specific integration.
4

Test the widget

Visit your website and verify the chat widget appears in the bottom-right corner. Click it to send a test message.

​
Configuration Options

​
Widget Appearance

​
widget_color
string
default:"#1f93ff"
Primary color for the widget (hex code)
​
welcome_title
string
Welcome message title shown when widget opens
​
welcome_tagline
string
Welcome message subtitle
​
reply_time
enum
Expected response time. Options: in_a_few_minutes, in_a_few_hours, in_a_day

​
Pre-Chat Form

Collect visitor information before starting a conversation:
​
pre_chat_form_enabled
boolean
default:"false"
Enable pre-chat form
​
pre_chat_form_options.pre_chat_message
string
Message shown at the top of the pre-chat form
​
pre_chat_form_options.require_email
boolean
default:"false"
Make email field required
​
pre_chat_form_options.pre_chat_fields
array
Custom fields to collect. Each field can have:
  • label - Field label
  • name - Field name/key
  • type - Field type (text, email, phone, select)
  • placeholder - Placeholder text
  • required - Whether field is required
  • values - Options for select fields

​
Security

​
hmac_mandatory
boolean
default:"false"
Require HMAC verification for user identity
​
allowed_domains
string
Comma-separated list of domains where widget is allowed (prevents unauthorized usage)
​
continuity_via_email
boolean
default:"true"
Allow continuing conversations via email when visitor is offline

​
Advanced Configuration

​
User Identity

Set user information when visitor is logged in: 
window.chatwootSDK.run({
  websiteToken: 'YOUR_WEBSITE_TOKEN',
  baseUrl: 'https://app.chatwoot.com',
  
  // User identification
  user: {
    identifier: '[email protected]',
    name: 'John Doe',
    email: '[email protected]',
    avatar_url: 'https://example.com/avatar.jpg',
    phone_number: '+1234567890'
  },
  
  // Custom attributes
  customAttributes: {
    accountId: '12345',
    pricingPlan: 'premium',
    signupDate: '2024-01-15'
  }
});

​
HMAC Verification

Secure user identity with HMAC verification: 
// Backend: Generate HMAC
const crypto = require('crypto');
const hmacToken = 'YOUR_HMAC_TOKEN'; // From Chatwoot inbox settings
const identifier = '[email protected]';
const hmac = crypto
  .createHmac('sha256', hmacToken)
  .update(identifier)
  .digest('hex');

// Frontend: Pass HMAC to widget
window.chatwootSDK.run({
  websiteToken: 'YOUR_WEBSITE_TOKEN',
  baseUrl: 'https://app.chatwoot.com',
  user: {
    identifier: '[email protected]',
    identifier_hash: hmac // HMAC from backend
  }
});
Never expose your HMAC token in frontend code. Always generate the HMAC hash on your backend server.

​
Locale/Language

Set the widget language: 
window.chatwootSDK.run({
  websiteToken: 'YOUR_WEBSITE_TOKEN',
  baseUrl: 'https://app.chatwoot.com',
  locale: 'es' // Spanish
});
Supported locales: en, es, fr, de, pt, pt_BR, ru, zh_CN, ja, ko, and more.

​
Widget Position

Customize widget position: 
window.chatwootSDK.run({
  websiteToken: 'YOUR_WEBSITE_TOKEN',
  baseUrl: 'https://app.chatwoot.com',
  position: 'left', // 'left' or 'right' (default)
  launcherTitle: 'Chat with us'
});

​
Widget SDK Methods

Control the widget programmatically: 
// Toggle widget visibility
window.$chatwoot.toggle();

// Open widget
window.$chatwoot.toggle('open');

// Close widget
window.$chatwoot.toggle('close');

// Set user information
window.$chatwoot.setUser('[email protected]', {
  name: 'John Doe',
  email: '[email protected]'
});

// Set custom attributes
window.$chatwoot.setCustomAttributes({
  accountId: '12345',
  plan: 'premium'
});

// Set labels
window.$chatwoot.setLabel('vip-customer');
window.$chatwoot.removeLabel('vip-customer');

// Reset session (log out)
window.$chatwoot.reset();
See Widget SDK documentation for complete API reference.

​
Best Practices

Load the widget asynchronously to avoid blocking page rendering
Set user identity and custom attributes for better context
Use HMAC verification in production to prevent identity spoofing
Configure pre-chat forms to collect important information upfront
Set appropriate business hours and response time expectations
Test widget behavior on mobile devices
Use allowed domains to prevent unauthorized usage

​
Troubleshooting

  • Verify the installation code is placed before </body>
  • Check browser console for JavaScript errors
  • Ensure websiteToken is correct
  • Check if domain is in allowed domains list
  • Verify Content Security Policy (CSP) allows loading from Chatwoot domain
  • Check if inbox is active in Chatwoot settings
  • Verify agents are assigned to the inbox
  • Check browser network tab for API errors
  • Ensure WebSocket connections are not blocked by firewall
  • Verify identifier is set correctly
  • For HMAC verification, ensure hash is generated correctly
  • Check that user information is set before widget loads

Build docs developers (and LLMs) love

Get started for freeTalk to us