chatsy

Site | NPM Module | GitHub Repo

Chatsy is an embeddable AI chatbot widget. Add intelligent customer support to any website with one line of code.

Free AI customer service chatbot agent

Quick Start

1. Create an Agent

Go to chatsy.ai/dashboard/agents/new to create your AI agent. Configure your brand info, knowledge base, response style, and welcome message. Copy the Agent ID when you're done.

2. Add to Your Website

Script tag (no build tools needed):

<script
  src="https://cdn.jsdelivr.net/npm/chatsy@latest/dist/chatsy.min.js"
  data-agent-id="YOUR_AGENT_ID"
></script>

A chat button appears in the bottom-right corner. Click it to open the chat.

NPM (for React, Vue, Next.js, etc.):

npm install chatsy

// ESM
import Chatsy from 'chatsy';

// CommonJS
const Chatsy = require('chatsy');

const chat = new Chatsy('YOUR_AGENT_ID');

Configuration

Script Tag Attributes

Attribute	Default	Description
data-agent-id	required	Your agent ID from the dashboard
data-button-background-color	#297bf7	Button background color
data-button-text-color	#FFFFFF	Button icon color
data-button-position	bottom-right	bottom-right or bottom-left
data-button-type	round	Button shape: round or square
data-button-icon	default	Icon style: default, material, or rounded

Note: User data (user, context) is not supported via script tag attributes. Use the JavaScript API with setUser() for dynamic user identification.

JavaScript Options

const chat = new Chatsy('YOUR_AGENT_ID', {
  settings: {
    button: {
      backgroundColor: '#297bf7', // Button background color
      textColor: '#FFFFFF',       // Button icon color
      position: 'bottom-right',   // 'bottom-right' or 'bottom-left'
      type: 'round',              // 'round' or 'square'
      icon: 'default',            // 'default', 'material', or 'rounded'
    },
  },
  user: {
    id: 'user-123',               // Unique user ID
    firstName: 'Jane',            // First name (avatar initials, sent to AI)
    lastName: 'Smith',            // Last name (avatar initials, sent to AI)
    email: 'jane@example.com',    // Sent to AI as context
    photoURL: 'https://...',      // Profile picture URL (replaces initials avatar)
    // ...any other scalar fields are sent to the AI
  },
  context: {
    // page.url, page.referrer, page.title are auto-collected
    tags: ['vip', 'enterprise'],  // Labels for filtering conversations
    metadata: { planId: 'pro' },  // Arbitrary key/values (scalars only)
  },
});

API

Methods

Method	Description
chat.open()	Open the chat window
chat.close()	Close the chat window
chat.toggle()	Toggle open/close
chat.send('Hello!')	Send a message programmatically
chat.setUser({ id, firstName, ... })	Update user identity (e.g., after auth state change)
chat.getMessages()	Get all messages as an array
chat.destroy()	Remove the widget from the page

Events

chat.on('ready', () => { /* Widget loaded */ });
chat.on('open', () => { /* Chat opened */ });
chat.on('close', () => { /* Chat closed */ });
chat.on('message', (msg) => { /* New message received */ });
chat.on('error', (err) => { /* Error occurred */ });

Multiple Instances

Each instance is independent, so you can run multiple widgets on the same page:

const support = new Chatsy('support-agent-id');
const sales = new Chatsy('sales-agent-id', {
  settings: { button: { position: 'bottom-left', backgroundColor: '#10B981' } },
});

How It Works

1. A floating chat button is injected into your page (a regular DOM element, not an iframe)
2. Clicking it lazily creates an iframe with the chat interface (no impact on initial page load)
3. Messages are sent to your AI agent via the Chatsy API
4. The agent responds based on your configured knowledge base, brand info, and instructions

Agent Configuration

Configure your agent at chatsy.ai/dashboard:

Setting	What It Does
Brand info	Company name, website, phone, description
Knowledge base	Products, services, and additional context the agent should know
Processes	Cancellation, refund, return, and shipping policies
Response style	Tone (professional, friendly, casual) and custom instructions
Welcome message	First message visitors see when opening chat
AI model	Standard (GPT-4o Mini) or Advanced (GPT-4o)

Development

npm start        # Watch mode - rebuilds on file changes
npm run build    # One-time build (ESM, CJS, UMD)
npm test         # Run tests

Build Outputs

File	Format	Use Case
dist/index.mjs	ESM	import in modern bundlers (webpack, Vite, etc.)
dist/index.js	CJS	require() in Node.js
dist/chatsy.min.js	IIFE (minified)	<script> tag / CDN

Local Testing

Open test/browser.html in your browser to test the widget locally.

License

MIT