Documentation

Everything you need to integrate ChikChak plugins into your React app. From first install to production deployment.

Overview

ChikChak Labs provides three React plugins that add customer engagement features to your app. Each plugin works independently or composes with the others:

💬

MessageCenter

Support tickets, live chat, team management, CSAT ratings

🛠

AdminCenter

Admin dashboard, role-based navigation, section groups

🐛

DebugCloud

Debug snapshots, error reporting, cache management

How it works

All plugins connect to the ChikChak Cloud — a hosted multi-tenant backend on AWS. You get a single API key that acts as both your license and your cloud connection. No database setup, no server deployment. Just install the npm package, add your API key, and ship.

Quick Start

Get a support ticket system running in your React app in under 5 minutes.

1

Get your API key

Contact us at support@chikchaklabs.com or sign up on our pricing page to get your API key. It looks like ck_live_abc123...

2

Install the package

npm install @chikchak/message-center
3

Add to your app

App.tsx 
import { createCloudAdapter } from '@chikchak/message-center/adapters/cloud';
import { MessageCenterProvider, MessagesPage } from '@chikchak/message-center';
import '@chikchak/message-center/styles';

// Create adapters using your API key
const adapters = createCloudAdapter({
  apiKey: 'ck_live_YOUR_API_KEY',
  // Optional: override default URLs
  // apiUrl: 'https://api.chikchaklabs.com',
  // wsUrl: 'wss://ws.chikchaklabs.com',
});

function App() {
  return (
    <MessageCenterProvider
      config={{
        siteId: 'your-site-name',
        ...adapters,
      }}
    >
      <MessagesPage />
    </MessageCenterProvider>
  );
}
4

That's it!

Your app now has support tickets, live chat, and team management. Customers can create tickets, chat with agents, and rate their support experience — all powered by the ChikChak Cloud backend.

How Licensing Works

Your API key is your license. One key does everything — authenticates your app, connects to the cloud backend, and determines which plugins and features are active.

🔑 API Key Format

Keys follow the format ck_live_ for production and ck_test_ for development. You'll receive your key when your license is created.

🌐 Domain Validation

Your license is locked to specific domains. The plugin only works on those domains. localhost always works for local development — no configuration needed.

📦 Plugin Access

Each key has specific plugins enabled (MessageCenter, AdminCenter, DebugCloud). If you try to use a plugin not included in your license, the cloud backend will reject the request.

📋 Plans

Trial — 14-day free evaluation
Basic — Essential features
Pro — Advanced features + priority support
Enterprise — Unlimited everything + SLA

⚠️ Keep your API key private

Your API key should be treated like a password. Don't commit it to public repositories. Use environment variables (VITE_CHIKCHAK_API_KEY) to keep it secure.

💬

MessageCenter

All-in-one customer support — tickets, live chat, canned responses, team management, and CSAT ratings.

Installation

npm install @chikchak/message-center

Basic Setup

App.tsx 
import { createCloudAdapter } from '@chikchak/message-center/adapters/cloud';
import { MessageCenterProvider, MessagesPage } from '@chikchak/message-center';
import '@chikchak/message-center/styles';

// Create adapters using your API key
const adapters = createCloudAdapter({
  apiKey: 'ck_live_YOUR_API_KEY',
  // Optional: override default URLs
  // apiUrl: 'https://api.chikchaklabs.com',
  // wsUrl: 'wss://ws.chikchaklabs.com',
});

function App() {
  return (
    <MessageCenterProvider
      config={{
        siteId: 'your-site-name',
        ...adapters,
      }}
    >
      <MessagesPage />
    </MessageCenterProvider>
  );
}

Available Components

imports.ts 
// Full messaging interface (tickets + chat)
import { MessagesPage } from '@chikchak/message-center';

// Individual components
import { TicketList } from '@chikchak/message-center';
import { TicketDetail } from '@chikchak/message-center';
import { AdminDashboard } from '@chikchak/message-center';

// Hooks
import { useMessageCenter } from '@chikchak/message-center';
import { useTickets } from '@chikchak/message-center';
Component Description
MessagesPageFull messaging UI — ticket list + detail view
TicketListStandalone ticket list with filtering and pagination
TicketDetailSingle ticket view with messages, notes, and activity
AdminDashboardAdmin panel with users, team, invites, announcements, and audit tabs

Custom Auth Adapter

If you have your own authentication system, provide a custom auth adapter:

CustomAuth.tsx 
import { createCloudAdapter } from '@chikchak/message-center/adapters/cloud';
import { MessageCenterProvider } from '@chikchak/message-center';

const adapters = createCloudAdapter({ apiKey: 'ck_live_YOUR_API_KEY' });

// Provide your own auth adapter
const authAdapter = {
  getUser() {
    // Return the currently logged-in user, or null
    return {
      userId: 'user-123',
      email: 'user@example.com',
      displayName: 'Jane Smith',
      groups: ['agents'],  // Include 'admins' for admin access
    };
  },
  onAuthChange(callback) {
    // Subscribe to auth state changes
    // Return an unsubscribe function
    return () => {};
  },
  async signOut() {
    // Sign the user out
  },
};

<MessageCenterProvider
  config={{
    siteId: 'your-site-name',
    auth: authAdapter,
    ...adapters,
  }}
>
  {/* your app */}
</MessageCenterProvider>

Features

🎫 Ticket System

Create, assign, categorize (Feature, Bug, General), set priority, track status

💬 Live Chat

Real-time WebSocket messaging with typing indicators and online status

📨 Canned Responses

Pre-built reply templates. One-click insert into conversations

⭐ CSAT Ratings

Post-resolution satisfaction surveys. Track team performance

🕐 Business Hours

Define hours, timezone support, holiday overrides, auto online/offline

👥 Team Management

Invite members, assign roles, track time, manage availability

🛠

AdminCenter

Flexible admin dashboard with pluggable sidebar sections, role-based navigation, and section groups.

Installation

npm install @chikchak/admin-center

Basic Setup

AdminApp.tsx 
import { createCloudAdapter } from '@chikchak/admin-center/adapters/cloud';
import { AdminCenterProvider, AdminPanel } from '@chikchak/admin-center';
import '@chikchak/admin-center/styles';

const adapters = createCloudAdapter({ apiKey: 'ck_live_YOUR_API_KEY' });

// Define your admin sidebar sections
const sections = [
  {
    id: 'dashboard',
    label: 'Dashboard',
    icon: DashboardIcon,
    component: DashboardSection,
  },
  {
    id: 'users',
    label: 'Users',
    icon: UsersIcon,
    component: UsersSection,
  },
];

function AdminApp() {
  return (
    <AdminCenterProvider
      config={{
        siteId: 'your-site-name',
        sections,
        ...adapters,
      }}
    >
      <AdminPanel />
    </AdminCenterProvider>
  );
}

Section Groups

Group related sections in the sidebar with collapsible headers and accent colors:

config.ts 
// Group related sections in the sidebar
const sectionGroups = [
  {
    id: 'support',
    label: 'Support',
    accentColor: '#3b82f6',
    sectionIds: ['tickets', 'live-chats', 'templates'],
  },
  {
    id: 'management',
    label: 'Management',
    ownerOnly: true,  // Only visible to owners
    accentColor: '#f59e0b',
    sectionIds: ['admin-users', 'security', 'roles'],
  },
];

<AdminCenterProvider
  config={{
    siteId: 'your-site-name',
    sections,
    sectionGroups,
    ...adapters,
  }}
>

Features

📑 Pluggable Sections

Register any React component as a sidebar section. Bring your own content

🔐 Role-Based Access

6 built-in roles with 18 permissions. Show/hide sections by role

📂 Section Groups

Collapsible sidebar groups with accent colors and owner-only visibility

🎨 Customizable

Custom brand colors, sidebar footer, header components, and CSS modules

🐛

DebugCloud

Production debugging tools — capture snapshots, report errors, manage caches, and sync debug data to the cloud.

Installation

npm install @chikchak/debug-cloud

Basic Setup

App.tsx 
import { DebugCloudProvider, DebugCloudPanel } from '@chikchak/debug-cloud';
import '@chikchak/debug-cloud/styles';

function App() {
  return (
    <DebugCloudProvider
      config={{
        apiKey: 'ck_live_YOUR_API_KEY',
        siteId: 'your-site-name',
      }}
    >
      {/* Your app */}
      <DebugCloudPanel />
    </DebugCloudProvider>
  );
}

Using the Hook

Access debug actions programmatically with the useDebugCloud hook:

DebugMenu.tsx 
import { useDebugCloud } from '@chikchak/debug-cloud';

function DebugMenu() {
  const { downloadSnapshot, resetCache, sendSnapshot } = useDebugCloud();

  return (
    <div>
      <button onClick={downloadSnapshot}>Download Debug Snapshot</button>
      <button onClick={resetCache}>Reset Cache</button>
      <button onClick={() => sendSnapshot('admin@example.com')}>
        Email Snapshot
      </button>
    </div>
  );
}

Capabilities

📸 Debug Snapshots

Capture full app state, console logs, network requests, and DOM snapshot

☁️ Cloud Sync

Upload snapshots to ChikChak Cloud for team review and analysis

🗑️ Cache Management

Reset service workers, clear storage, and manage browser caches

📧 Email Reports

Send debug snapshots directly to email for remote debugging

Embed Widget

Add live chat to any website with a single script tag. No React required. Works on WordPress, Shopify, static HTML — anything.

Installation

Add this script tag before the closing </body> tag on your page:

index.html 
<!-- Add to any HTML page -->
<script
  src="https://cdn.chikchaklabs.com/embed/chikchak-widget.min.js"
  data-api-key="ck_live_YOUR_API_KEY"
  data-site-id="your-site-name"
></script>

What it includes

  • ✓ Floating chat bubble in the bottom-right corner
  • ✓ Full ticket submission form
  • ✓ Real-time chat with agents via WebSocket
  • ✓ 159KB gzipped — loads asynchronously, no performance impact

Configuration Attributes

Attribute Required Description
data-api-key Yes Your ChikChak API key
data-site-id Yes Your site identifier
data-position No "bottom-right" (default) or "bottom-left"
data-theme No "light" (default) or "dark"

Configuration

All plugins share a common configuration pattern. Pass your API key and site ID, and the cloud adapter handles everything else.

Shared Config

config.ts 
// All plugins accept these shared config options
{
  siteId: string;        // Your site identifier
  apiKey?: string;       // Your ChikChak API key (ck_live_xxx)
  cloudApiUrl?: string;  // Default: https://api.chikchaklabs.com
  cloudWsUrl?: string;   // Default: wss://ws.chikchaklabs.com
}

Environment Variables

Keep your API key out of source code using environment variables:

.env 
# .env (add to .gitignore!)
VITE_CHIKCHAK_API_KEY=ck_live_YOUR_API_KEY
VITE_CHIKCHAK_SITE_ID=your-site-name
App.tsx 
const adapters = createCloudAdapter({
  apiKey: import.meta.env.VITE_CHIKCHAK_API_KEY,
});

<MessageCenterProvider config={{
  siteId: import.meta.env.VITE_CHIKCHAK_SITE_ID,
  ...adapters,
}}>

Adapter Pattern

ChikChak plugins use an adapter pattern so you can swap backends without changing UI code. Three options:

☁️ Cloud Adapter Recommended

Uses ChikChak Cloud (our hosted backend). Zero setup. Just provide your API key.

🔗 REST Adapter

Point to your own REST API. You implement the endpoints; we provide the interface contracts.

⚡ Amplify Adapter

Use AWS Amplify for auth and data. Great if you're already on AWS.

API Reference

The ChikChak Cloud API is a REST API at https://api.chikchaklabs.com. All requests require your API key in the x-api-key header.

Endpoint Description
POST /auth/signupRegister a new user
POST /auth/loginSign in and get JWT
GET /ticketsList tickets (with pagination)
POST /ticketsCreate a new ticket
GET /tickets/:idGet ticket details
PUT /tickets/:idUpdate ticket
POST /tickets/:id/messagesSend a message
GET /users/:idGet user profile
GET /agentsList agents
GET /business-hoursGet business hours config
GET /configGet site configuration

All endpoints return JSON. WebSocket connections use wss://ws.chikchaklabs.com for real-time updates. Full API documentation coming soon.

FAQ

Do I need to set up a database?
No. When using the Cloud adapter (recommended), everything is hosted on our infrastructure — DynamoDB, S3, WebSocket, authentication. You just add your API key and it works.
Can I use my own backend instead of ChikChak Cloud?
Yes! Use the REST adapter to point to your own API, or the Amplify adapter if you're on AWS. The adapter pattern means you can swap backends without changing any UI code.
Does localhost work for development?
Yes. localhost is always allowed regardless of your domain configuration. You don't need to add it to your license — just start developing.
Can I use the plugins without React?
For live chat, yes! Use the Embed Widget — a single script tag that works on any website (WordPress, Shopify, static HTML). For the full plugin suite (tickets, admin, debug), React is required.
What happens when my license expires?
The cloud backend will reject requests with an expired key. Your plugins will show an expired state to users. Renew your license to restore functionality. Your data is preserved — nothing gets deleted.
How many domains can I use with one API key?
It depends on your license. Most keys allow 1-2 domains. Enterprise plans can have unlimited domains. Contact us if you need more.
Is my data secure?
Yes. All data is encrypted at rest (AES-256) and in transit (TLS 1.2+). The cloud backend runs on AWS with DynamoDB Point-in-Time Recovery, rate limiting, and domain-level multi-tenant isolation. Each customer's data is fully isolated.

Need help getting started?

We're here to help you integrate ChikChak plugins into your app.

Contact Support GitHub