Custom Chat Widget (Composable Mode)

Build your own chat interface with complete control over HTML, CSS, and behavior. Perfect for brands that need pixel-perfect designs.

Overview

The Custom Widget Mode provides a ~9KB (gzipped) SDK that handles:

• Authentication (signup, login, session persistence)
• Conversations (list, create, open)
• Messages (send, receive, real-time updates)
• Knowledge Base (search articles, get stats)
• File attachments (upload, display)
• Push notifications
• Typing indicators

You provide the HTML and CSS—we handle everything else.

Installation

Add the SDK to your page:

<div data-cstar-launcher style="display:none"></div>
<script src="https://cstar.help/widget/chat.js?team=YOUR_TEAM"></script>

The hidden data-cstar-launcher div tells the SDK to skip the prebuilt UI and expose window.CStarChat for your custom code.

Authentication

Signup

const result = await CStarChat.signup({
  email: 'customer@example.com',
  name: 'Jane Doe',
  password: 'securepass123'
});
// Session is stored automatically in localStorage
// result.customer contains the customer object

Login

const result = await CStarChat.login({
  email: 'customer@example.com',
  password: 'securepass123'
});
// Session restored, conversations loaded automatically

Session Persistence

The SDK stores sessions in localStorage as cstar_session_{teamSlug}. Sessions are automatically restored on page load — returning customers don't need to log in again.

// Check if customer is already identified
if (CStarChat.isIdentified()) {
  const customer = CStarChat.getCustomer();
  console.log('Welcome back,', customer.name);
}

// Listen for auth events
CStarChat.on('identify', () => {
  console.log('Customer logged in');
});

CStarChat.on('logout', () => {
  console.log('Customer logged out');
});

Logout

CStarChat.logout();
// Clears session from localStorage

Panel Control

CStarChat.open();     // Open the chat panel
CStarChat.close();    // Close it
CStarChat.toggle();   // Toggle open/close
CStarChat.isOpen();   // Check state

Conversations

// Start a new conversation
const result = await CStarChat.startConversation({
  subject: 'Help with billing',
  message: 'I need to update my payment method.'
});

// Send a message in the current conversation
CStarChat.send('Thanks for the quick response!');

// Get all conversations
const conversations = CStarChat.getConversations();

// Open a specific conversation
CStarChat.openConversation(conversationId);

Knowledge Base (Library)

Access your public knowledge base directly from the SDK — no separate API calls needed.

Search Articles

const results = await CStarChat.searchArticles('webhook setup', 5);
// results.data = [{ id, title, slug, excerpt, view_count, ... }]

Get a Single Article

const article = await CStarChat.getArticle('api-authentication');
// article.data = { id, title, slug, content, view_count, ... }
// Note: content is markdown — use a library like marked.js to render as HTML

Get Popular Articles

const popular = await CStarChat.getPopularArticles(5);
// popular.data = top 5 articles sorted by view count

Get Categories

const categories = await CStarChat.getCategories();
// categories.data = [{ id, name, slug, article_count, ... }]

Get Library Stats

const stats = await CStarChat.getLibraryStats();
// stats = { articles: 61, categories: 10, views: 462, popularArticles: [...] }

Tip: Article content is returned as markdown. Use a library like marked to convert it to HTML before rendering.

Real-Time Events

CStarChat.on('message:received', (msg) => {
  console.log(msg.agentName + ': ' + msg.content);
});

CStarChat.on('unread', (count) => {
  updateBadge(count);
});

CStarChat.on('ready', () => {
  console.log('SDK initialized');
});

Data Attributes Reference

For declarative HTML binding, use data-cstar-* attributes:

Actions

Attribute	Description
data-cstar-launcher	Toggle open/close (also enables custom mode)
data-cstar-open	Open panel
data-cstar-close	Close panel
data-cstar-send	Send current message
data-cstar-new-conversation	Start new conversation
data-cstar-logout	Log out customer

Inputs

Attribute	Description
data-cstar-input="messageDraft"	Message text input
data-cstar-input="subject"	New conversation subject
data-cstar-input="authEmail"	Email for auth
data-cstar-input="authName"	Name for signup
data-cstar-input="authPassword"	Password for auth

Containers

Attribute	Description
data-cstar-panel	Main chat panel
data-cstar-view="name"	View container
data-cstar-conversations	Conversation list
data-cstar-messages	Message list

Tips

1. Start simple - Get basic messaging working first
2. Use semantic HTML - Accessibility matters
3. Test on mobile - Touch targets should be 42px+
4. Match your brand - That's the whole point!
5. Handle markdown - Article content is markdown, convert to HTML before rendering

Live Example

Our own support page at cstar.help/support is built entirely with this SDK. The chat widget, article search, and self-service features all use the same CStarChat methods documented here.