Skip to main content

​
Widget Apps

Widget Apps are embeddable chat interfaces that you can add to any website or application. Customize the appearance, behavior, and functionality to match your brand and use case.

​
Creating a Widget App

Every agent in ChatterMate has an associated widget that can be embedded on your website.
1

Create or Select an Agent

Navigate to Agents in the dashboard and create a new agent or select an existing one.
2

Open Widget Tab

Click on the Widget tab in the agent configuration.
3

Copy Widget Code

Copy the provided code snippet.
4

Add to Your Website

Paste the code just before the closing </body> tag on your website.

​
Chat Styles

Choose the chat style that best fits your use case:

​
Traditional Support Interface

The classic customer support chat experience with agent branding.Features:
  • Email collection before chat starts
  • Agent avatar and name displayed
  • Formal, business-focused layout
  • “Powered by ChatterMate” branding
  • Standard greeting message
Best for:
  • Customer support portals
  • E-commerce websites
  • Service-based businesses
  • Help desk interfaces

​
Integration Methods

Script Integration (Recommended)

Simple, lightweight integration with a single script tag. Automatically handles updates and optimizations.

iFrame Integration

Embed as an iframe for more control over placement and dimensions. Useful for specific layout requirements.

​
Script Integration

Add this code before your closing </body> tag: 
<script>
  window.chattermateId = 'YOUR_WIDGET_ID';
</script>
<script src="https://app.chattermate.chat/webclient/chattermate.min.js"></script>

​
iFrame Integration

For iframe embedding: 
<iframe
  src="https://api.chattermate.chat/api/v1/widgets/YOUR_WIDGET_ID/data"
  frameborder="0"
  width="400"
  height="600"
  allow="clipboard-write"
  style="border-radius: 24px;">
</iframe>

​
Customization Options

​
Visual Customization

Customize your widget’s appearance in the Chat Customization tab:
OptionDescription
Background ColorMain background of the chat interface
Chat Bubble ColorColor of message bubbles
Accent ColorButtons, links, and interactive elements
Font FamilyTypography (Inter, system-ui, sans-serif)

​
Welcome Messages (Ask Anything Style)

FieldDescriptionMax Length
Welcome TitleMain greeting headline100 characters
Welcome SubtitleDescriptive text about capabilities250 characters
Example: 
Title: "Welcome to TechSupport AI"
Subtitle: "I can help you troubleshoot issues, find documentation,
and answer questions about our products. What can I help you with?"

​
CSS Variables

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;
}

​
Widget Events

The widget communicates via postMessage events:

​
Listen for Events

window.addEventListener('message', (event) => {
  switch(event.data.type) {
    case 'TOKEN_UPDATE':
      // New conversation token generated
      const token = event.data.token;
      localStorage.setItem('ctid', token);
      break;

    case 'CHAT_OPENED':
      // Widget was opened
      console.log('Chat opened');
      break;

    case 'CHAT_CLOSED':
      // Widget was closed
      console.log('Chat closed');
      break;
  }
});

​
Send Commands

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

// Update customization
window.postMessage({
  type: 'CUSTOMIZATION_UPDATE',
  data: {
    chat_bubble_color: '#f34611'
  }
}, '*');

​
Domain Restrictions

Protect your widget from unauthorized embedding:
1

Access Agent Settings

Navigate to your agent’s configuration.
2

Configure Allowed Domains

Add domains that are allowed to embed your widget.
3

Enable Domain Validation

Turn on domain checking to block unauthorized sites.
When domain restrictions are enabled, the widget will only load on whitelisted domains. Requests from other domains will be blocked.

​
Mobile Responsiveness

The widget automatically adapts to different screen sizes: 
.widget-container {
  width: 400px;
  height: 600px;
  border-radius: 24px;
  position: fixed;
  bottom: 20px;
  right: 20px;
}

​
Mobile Features

  • Full-screen chat interface on mobile devices
  • Touch-optimized buttons and inputs
  • Smooth animations and transitions
  • Keyboard-aware input positioning

​
Widget Features

Real-time Chat

Instant messaging with typing indicators and read receipts

File Attachments

Share images and documents in conversations

Markdown Support

Rich text formatting in messages

Emoji Support

Full emoji picker for expressive conversations

Message History

Persistent conversation history across sessions

Human Handoff

Seamless transfer to human agents when needed

​
Best Practices

  1. Placement
    • Add script just before closing </body> tag
    • Ensure no conflicting CSS styles
    • Test on multiple pages
  2. Performance
    • The widget loads asynchronously
    • Minimal impact on page load time
    • Consider lazy loading on high-traffic pages
  3. User Experience
    • Test on both desktop and mobile
    • Verify email collection flow (Chatbot style)
    • Check conversation history persistence
    • Test offline/reconnection behavior
  4. Branding
    • Match colors to your brand
    • Use consistent typography
    • Customize welcome messages for your audience

​
Troubleshooting

  • Verify widget ID is correct
  • Check browser console for JavaScript errors
  • Ensure script is placed before </body> tag
  • Check if ad blockers are interfering
  • Widget uses scoped CSS to minimize conflicts
  • Check for global CSS rules affecting the widget
  • Use browser DevTools to identify conflicting styles
  • Ensure viewport meta tag is present: <meta name="viewport" content="width=device-width, initial-scale=1">
  • Check for CSS that might affect fixed positioning
  • Test in actual mobile devices, not just browser emulation
  • Verify localStorage is available and not blocked
  • Check if cookies/storage are being cleared
  • Ensure same widget ID is used across pages

​
What’s Next?

After deploying your widget:
  1. Configure authentication for secure access
  2. Enable file attachments if needed
  3. Set up human agent handoff
  4. Monitor conversations in the dashboard

Authentication

Learn how to secure your widget with token authentication