​
Widget Integration

Add the ChatterMate chat widget to your website using either direct script integration or iframe embedding.
Widget Integration Options

​
Integration Methods

Add the following code snippet to your website’s HTML, just before the closing </body> tag: 
<script>
  window.chattermateId='YOUR_WIDGET_ID';
</script>
<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>
Replace YOUR_WIDGET_ID with your unique widget identifier from the ChatterMate dashboard.

​
2. IFrame Integration

Alternatively, embed the chat widget using an iframe: 
<iframe 
  src="https://api.chattermate.chat/api/v1/widgets/YOUR_WIDGET_ID/data"
  frameborder="0"
  width="450" 
  height="600"
  allow="clipboard-write">
</iframe>
The iframe method is useful for testing or when you need more control over the widget’s placement and dimensions.

​
Widget Configuration

​
Customization

// Update chat bubble color
window.postMessage({
  type: 'CUSTOMIZATION_UPDATE',
  data: {
    chat_bubble_color: '#f34611'  // Your brand color
  }
}, '*');

​
Mobile Responsiveness

The widget automatically adapts to different screen sizes: 
width: 400px;
height: 600px;
border-radius: 24px;

​
Event Handling

The widget supports the following events:

​
Token Management

// Listen for token updates from the widget
window.addEventListener('message', (event) => {
  if (event.data.type === 'TOKEN_UPDATE') {
    // Store the token securely
    const token = event.data.token;
    localStorage.setItem('ctid', token);
  }
});

​
Scroll Control

// Scroll chat to bottom
window.postMessage({
  type: 'SCROLL_TO_BOTTOM'
}, '*');

​
Security Features

  • Tokens are encrypted and stored securely
  • Communication uses postMessage for security
  • Automatic token management
  • Domain validation for widget loading

​
Widget Features

​
Customer Identification

  • Email collection before chat starts
  • Automatic returning customer detection
  • Previous conversation history loading
  • Context maintenance across sessions

​
Chat Interface

  • Real-time message updates
  • Typing indicators
  • Message status tracking
  • File attachment support
  • Markdown formatting support
  • Emoji support

​
Styling

The widget uses CSS variables for consistent theming: 
:root {
  --primary-color: #f34611;
  --background-base: #ffffff;
  --text-color: #1F2937;
  --border-color: #E5E7EB;
  --radius-lg: 24px;
  --space-md: 16px;
  --space-sm: 8px;
}

​
Testing Your Integration

​
Test Project

We provide a sample test project at github.com/chattermate/chattermate.chat/tree/main/chattermate-test:
  1. Clone and setup:
git clone https://github.com/chattermate/chattermate.chat
cd chattermate-test
npm install
  1. Start test server:
npm start
  1. Open http://localhost:3000 and enter your widget ID
The test project demonstrates:
  • Basic widget initialization
  • Token management
  • Style customization
  • Mobile responsiveness

​
Best Practices

  1. Implementation
    • Add script just before closing body tag
    • Enable secure token storage
    • Test on multiple browsers
    • Verify mobile responsiveness
  2. Security
    • Store tokens securely
    • Use HTTPS only
    • Implement proper CSP headers
    • Enable domain restrictions
  3. User Experience
    • Test email collection flow
    • Verify history loading
    • Check offline behavior
    • Test connection handling

​
Troubleshooting

​
What’s Next?

After integrating the widget:
  1. Test customer identification flow
  2. Verify conversation persistence
  3. Monitor connection stability
  4. Test mobile responsiveness

Human Agents

Next: Learn how to manage human agents