Widget Integration

Add the ChatterMate chat widget to your website using either direct script integration or iframe embedding, then choose where it sits and how visitors open it.

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.

Placement

By default the launcher is a round bubble 20px from the bottom-right corner, and the chat window opens above it. You can change that in two places:

In the dashboard — the Widget placement section of your agent’s Customization tab. These are the defaults for every site the agent is embedded on.
In the embed snippet — anything you set on the page wins over the dashboard, so one agent can look different on your pricing page than in your docs.

Colours, fonts and the chat design itself are set in the same Customization tab; placement is only about where the widget sits and how it opens.

Floating bubble

displayMode: 'floating' — the default, on the left or right, with a chat window above it.

Sidebar drawer

displayMode: 'sidebar-left' or 'sidebar-right' — a full-height panel sliding in from that edge.

Search bar

displayMode: 'search-bar' — the launcher becomes a search-style bar that opens a centered palette.

No launcher

launcher: false — nothing is drawn until you open the chat from your own button.

The search bar mode needs the Ask Anything or Aurora chat design, because those are the two designs that open as a command palette. The dashboard greys the option out for other designs.

Setting placement on the page

Set window.chattermateConfig before the loader script. No JavaScript calls needed:

<script>
  window.chattermateId = 'YOUR_WIDGET_ID';
  window.chattermateConfig = {
    displayMode: 'sidebar-right',
    sidebarWidth: 460
  };
</script>
<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>

ChatterMate.init() takes exactly the same options if you prefer to configure the widget after the script has loaded:

ChatterMate.init({
  id: 'YOUR_WIDGET_ID',
  displayMode: 'floating',
  position: { side: 'left', bottom: 90, offset: 24 },
  width: 520,
  height: 700
});

Options

Option	Type	Default	Description
`id`	string	—	Your widget ID. Same value as `window.chattermateId`.
`displayMode`	`'floating'` · `'sidebar-left'` · `'sidebar-right'` · `'search-bar'`	`'floating'`	How the widget is presented.
`position.side`	`'left'` · `'right'`	`'right'`	Which edge the launcher and window hug.
`position.bottom`	number (px)	`20`	Distance from the bottom edge. Raise it to clear a fixed bottom bar.
`position.offset`	number (px)	`20`	Distance from the chosen side edge.
`width`	number (px)	`400`	Chat window width in floating mode (280–800).
`height`	number (px)	`560`	Chat window height in floating mode (400–900).
`sidebarWidth`	number (px)	`420`	Drawer width in the sidebar modes (320–640).
`searchBar.placeholder`	string	`'Ask anything...'`	Text shown in the search bar, up to 80 characters.
`searchBar.width`	number (px)	`320`	Width of the search bar trigger.
`launcher`	boolean	`true`	`false` hides the built-in launcher — see Using your own button.
`trigger`	CSS selector	—	Elements that toggle the chat when clicked.
`zIndex`	number	`999999`	Stacking base, if the widget collides with your own overlays.
`hotkey`	boolean	`true`	`false` releases ⌘K / Ctrl+K, if your site already uses it.
`baseUrl`	string	cloud API	Self-hosted only — your API URL. Usually set via `window.chattermateBaseUrl`.
`tokenProvider`	async function	—	Returns a fresh `/generate-token` token when the widget can no longer renew the visitor’s identity — see Staying signed in.

The legacy form position: { bottom, right } still works — right is treated as offset — so existing installations need no changes.

You can also reposition the widget after it has loaded, which is useful when your layout changes:

ChatterMate.setPosition({ side: 'left', bottom: 100, offset: 24 });

Mobile

On small screens the chat always opens full-screen, whichever display mode you choose. Your offsets still control where the closed launcher sits, so it can be kept clear of a bottom navigation bar.

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

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

Using your own button

Hide the built-in launcher and open the chat from an element of your own. There are three ways, and none of them requires you to write an event handler.

data-chattermate-open
A CSS selector
The JS API

Add the attribute to any element. It works for elements added to the page later, too.

<button data-chattermate-open>Chat with us</button>

Point trigger at your own selector — handy when you cannot change the markup.

<script>
  window.chattermateId = 'YOUR_WIDGET_ID';
  window.chattermateConfig = {
    launcher: false,
    trigger: '.js-support-link'
  };
</script>
<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>

Call the API from your own code.

document.querySelector('#help').addEventListener('click', () => {
  ChatterMate.open();
});

With the launcher hidden there is nowhere to show the unread badge or the greeting nudge. Listen for the unread event if you want to show a count on your own button.

JavaScript API

window.ChatterMate is available as soon as the loader script runs. Calls that arrive before the widget has finished loading are queued and applied once it is ready, so you do not have to wait.

Method	Description
`ChatterMate.init(options)`	Configure the widget. Same options as `window.chattermateConfig`.
`ChatterMate.open(options?)`	Open the chat. Pass `{ message }` to prefill the input.
`ChatterMate.close()`	Close the chat.
`ChatterMate.toggle()`	Open if closed, close if open.
`ChatterMate.isOpen()`	`true` while the chat is open.
`ChatterMate.showLauncher()`	Show the built-in launcher.
`ChatterMate.hideLauncher()`	Hide the built-in launcher.
`ChatterMate.setPosition(position)`	Move the widget: `{ side, bottom, offset }`.
`ChatterMate.identify(token)`	Switch to the visitor the token identifies (SPA login).
`ChatterMate.logout()`	Drop the current identity and conversation, back to anonymous.
`ChatterMate.destroy()`	Remove the widget from the page entirely.
`ChatterMate.reload()`	Rebuild the widget, and bring back a destroyed one.
`ChatterMate.on(event, handler)`	Subscribe to an event.
`ChatterMate.off(event, handler)`	Unsubscribe.

Prefilling a message

open({ message }) puts text in the input without sending it, so the visitor can edit it or just press enter. Good for “Ask about pricing” links next to a plan:

ChatterMate.open({ message: 'Tell me about the Pro plan' });

The widget’s identity is fixed when it loads — the token it starts with decides whose conversation it shows. An app that signs a visitor in or out without reloading the page has to say so, or the widget keeps the identity it had when the script first ran: anonymous after a login, the previous user after a logout.

// After login — token from your backend's /generate-token call
ChatterMate.identify(token);

// After logout — back to a fresh anonymous visitor
ChatterMate.logout();

A change of visitor rebuilds the widget in place: the chat closes, the previous conversation is closed on the server too, and the widget reloads as the new person. identify() with the token the widget is already running on does nothing, so it is safe to call on every route change. Handing identify() a fresher token for the same visitor is not a change of identity: the widget takes the new token and keeps the conversation open, so re-authenticating never costs someone the chat they are in the middle of. Two more lifecycle methods:

ChatterMate.destroy();   // take the widget off the page completely
ChatterMate.reload();    // rebuild it — also brings back a destroyed widget

destroy() removes the launcher, the chat frame, the injected styles, and every listener and timer the loader added, so nothing of ours is left on the page. It does not clear the stored identity — a later reload() comes back as the same visitor, so use logout() if that is what you want.

With token authentication required, logout() leaves the widget without a token and it cannot load. Pair it with hideLauncher(), or call destroy() instead.

Staying signed in on a long-lived page

A token from /generate-token lasts as long as you asked for — an hour by default. The widget renews it on its own well before it lapses, so a tab left open all day keeps the visitor signed in, and a new chat they start hours later still arrives in your inbox as that person, with their custom_data. Renewal keeps the same customer and the same lifetime, and stops if you revoke the token. It cannot run forever: after 30 days your app has to identify the visitor again. That only leaves the case where the widget has no live token to renew — the tab was asleep past the expiry, or the token was revoked. The widget cannot mint one itself (that needs your API key), so give it a way to ask:

window.chattermateConfig = {
  tokenProvider: async () => {
    const res = await fetch('/api/chattermate-token');   // your endpoint
    return (await res.json()).token;                     // from /generate-token
  }
};

tokenProvider is called only when the widget needs a token you alone can issue. The replacement is handed to the running widget, so the visitor keeps the conversation they were in. Without one, the widget falls back to an anonymous visitor and fires identityExpired so you can react yourself.

Return a token for the same person. tokenProvider replaces an identity that ran out; it is not a way to switch visitors — use identify() for that.

Events

Event	Fires when	Payload
`ready`	The widget has loaded and the API is live	—
`open`	The chat opens	—
`close`	The chat closes	—
`unread`	The unread agent-message count changes	`count` (number)
`chatCreated`	A new conversation starts — the visitor used New chat, or this is their first of the visit	`{ sessionId, authenticated }`
`identityExpired`	The token the widget was identified with has run out and cannot be renewed	—

ChatterMate.on('ready', () => console.log('widget ready'));
ChatterMate.on('open', () => analytics.track('chat_opened'));
ChatterMate.on('unread', (count) => {
  document.querySelector('#chat-badge').textContent = count || '';
});

ChatterMate.on('chatCreated', ({ sessionId, authenticated }) => {
  if (!authenticated) console.warn('new chat started as an anonymous visitor');
});

authenticated is false when the conversation belongs to an anonymous visitor rather than the person you identified — a signal that the widget is running without a live token from /generate-token.

ready fires only once. If you subscribe after it has already happened — for example from consent-gated or lazily loaded code — your handler is called immediately rather than never.

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, shown only while a reply is actually being written
Message status tracking
File attachment support
Markdown formatting support
Emoji support

Availability

The line under the agent’s name reflects who is answering.

While the AI is answering it reads Online · replies instantly, which holds at any hour
When a person has to answer — an agent in human mode, or a chat a teammate has taken over — it follows your organization’s business hours: usually replies in a few minutes while you are open, we’ll reply when we’re back outside them

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.chat/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

Placement gallery

http://localhost:3000/ui-options.html is a gallery of every placement option — one card per scenario, each opening a page with the widget configured that way and buttons wired to the JS API. Each card runs in one of two modes, chosen at the top of the gallery:

Stub fakes the widget entirely, so you can check placement, the JS API and the events with no backend running.
Real loads your actual widget — fill in your widget ID and API URL first.

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

Nothing appears on the page

Check whether Hide launcher is on in the Widget placement section — with no launcher, the chat only opens from your own button or ChatterMate.open()
If your site has a high-stacking header or modal, raise zIndex
Confirm the loader script actually loaded and window.ChatterMate is defined

The search bar mode is greyed out

It needs the Ask Anything or Aurora chat design, set under Customization → Chat design

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

Placement

Ways to present the widget

Floating bubble

Sidebar drawer

Search bar

No launcher

Setting placement on the page

Options

Mobile

Using your own button

JavaScript API

Prefilling a message

Staying signed in on a long-lived page

Events

Event Handling

Token Management

Scroll Control

Security Features

Widget Features

Customer Identification

Chat Interface

Availability

Styling

Testing Your Integration

Test Project

Placement gallery

Best Practices

Troubleshooting

What’s Next?

Human Agents

​Widget Integration

​Integration Methods

​1. Script Integration (Recommended)

​2. IFrame Integration

​Placement

​Ways to present the widget

Floating bubble

Sidebar drawer

Search bar

No launcher

​Setting placement on the page

​Options

​Mobile

​Using your own button

​JavaScript API

​Prefilling a message

​Login and logout in a single-page app

​Staying signed in on a long-lived page

​Events

​Event Handling

​Token Management

​Scroll Control

​Security Features

​Widget Features

​Customer Identification

​Chat Interface

​Availability

​Styling

​Testing Your Integration

​Test Project

​Placement gallery

​Best Practices

​Troubleshooting

​What’s Next?

Human Agents

Widget Integration

Integration Methods

1. Script Integration (Recommended)

2. IFrame Integration

Placement

Ways to present the widget

Setting placement on the page

Options

Mobile

Using your own button

JavaScript API

Prefilling a message

Login and logout in a single-page app

Staying signed in on a long-lived page

Events

Event Handling

Token Management

Scroll Control

Security Features

Widget Features

Customer Identification

Chat Interface

Availability

Styling

Testing Your Integration

Test Project

Placement gallery

Best Practices

Troubleshooting

What’s Next?