Widget Integration

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

Integration Methods

1. Script Integration (Recommended)

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.

Customization

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

By default the launcher sits 20px from the bottom-right corner. To move it — for example, to clear a fixed bottom navigation bar — initialize the widget with ChatterMate.init() and pass a position. Both values are in pixels, measured from the bottom and right edges of the screen. The chat window stays anchored above the launcher, and the offset applies on mobile too.

<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>
<script>
  ChatterMate.init({
    id: 'YOUR_WIDGET_ID',
    position: { bottom: 100, right: 24 }
  });
</script>

You can also reposition the widget at any time after it has loaded — useful when your layout changes, such as a bottom bar appearing:

ChatterMate.setPosition({ bottom: 100, right: 24 });

position and setPosition() accept bottom and right in pixels. On mobile the chat window opens full-screen, so the offset controls where the closed launcher button sits — handy for keeping it clear of a bottom navigation bar.

Mobile Responsiveness

The widget automatically adapts to different screen sizes:

width: 400px;
height: 600px;
border-radius: 24px;

width: 100%;
height: 100vh;
border-radius: 0;

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

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:

Clone and setup:

git clone https://github.com/chattermate/chattermate.chat
cd chattermate-test
npm install

Start test server:

npm start

Open http://localhost:3000 and enter your widget ID

The test project demonstrates:

Basic widget initialization
Token management
Style customization
Mobile responsiveness

Best Practices

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

Troubleshooting

Token Issues

Verify localStorage access
Check token storage events
Clear stored tokens and retry
Verify domain permissions

Display Problems

Check CSS variables
Verify mobile breakpoints
Test iframe dimensions
Validate color codes

Connection Issues

Verify widget ID
Check network connectivity
Test WebSocket connection
Validate API endpoints

What’s Next?

After integrating the widget:

Test customer identification flow
Verify conversation persistence
Monitor connection stability
Test mobile responsiveness

Human Agents

Next: Learn how to manage human agents

Getting Started

Features

Channels

Developer Tools

Deployment

Widget Integration

Integration Methods

1. Script Integration (Recommended)

2. IFrame Integration

Widget Configuration

Customization

Widget Position

Mobile Responsiveness

Event Handling

Token Management

Scroll Control

Security Features

Widget Features

Customer Identification

Chat Interface

Styling

Testing Your Integration

Test Project

Best Practices

Troubleshooting

What’s Next?

Human Agents

​Widget Integration

​Integration Methods

​1. Script Integration (Recommended)

​2. IFrame Integration

​Widget Configuration

​Customization

​Widget Position

​Mobile Responsiveness

​Event Handling

​Token Management

​Scroll Control

​Security Features

​Widget Features

​Customer Identification

​Chat Interface

​Styling

​Testing Your Integration

​Test Project

​Best Practices

​Troubleshooting

​What’s Next?

Human Agents

Widget Integration

Integration Methods

1. Script Integration (Recommended)

2. IFrame Integration

Widget Configuration

Customization

Widget Position

Mobile Responsiveness

Event Handling

Token Management

Scroll Control

Security Features

Widget Features

Customer Identification

Chat Interface

Styling

Testing Your Integration

Test Project

Best Practices

Troubleshooting

What’s Next?