Kaily Chat SDK

The @kaily-ai/chat-sdk package is the official TypeScript SDK for integrating Kaily.ai copilot chat into your app. It connects over HTTP and WebSockets (Socket.io) for streaming replies, thread management, custom tools, and user context.

• npm: npmjs.com/package/@kaily-ai/chat-sdk

Installation

npm install @kaily-ai/chat-sdk

Use yarn or pnpm if you prefer.

Quick start

Initialize the platform, create a bot with your copilot app token, then send a message with streaming listeners:

import { CopilotPlatform } from '@kaily-ai/chat-sdk';

const copilot = CopilotPlatform.getInstance({
  environment: 'production', // 'production' | 'uat' | 'sit'
  surfaceClient: 'web',
});

const bot = await copilot.createBotInstance('YOUR_APP_TOKEN');

await bot.message(
  { text: 'Hello!' },
  {
    deltaListener: (res) => console.log('Streaming:', res.data.content),
    replyListener: (res) => console.log('Reply:', res.data),
    progressListener: (res) => console.log('Progress:', res.data.progress),
    toolMessageListener: (res) => console.log('Tool:', res.data),
  }
);

Multi-instance (multiple widgets)

For more than one independent widget on the same page:

const sales = CopilotPlatform.createInstance('sales', {
  environment: 'production',
  surfaceClient: 'web',
});

const salesBot = await sales.createBotInstance('SALES_APP_TOKEN');
// Later: CopilotPlatform.getInstanceById('sales')

Messaging

Use bot.message to send user input and subscribe to streaming deltas, the final reply, progress, and tool output. Pass an optional thread_id to continue an existing conversation.

const result = await bot.message(
  {
    text: 'What is the status of my order?',
    thread_id: 'optional-thread-id',
  },
  {
    deltaListener: (res) => {
      // Real-time streaming chunks
      console.log(res.data.content);
    },
    replyListener: (res) => {
      // Final complete response
      console.log(res.data.messages);
    },
    progressListener: (res) => {
      // Progress updates (e.g., "Searching...")
      console.log(`${res.data.progress}%`, res.data.content);
    },
    toolMessageListener: (res) => {
      // Tool execution output
      console.log(res.data.content);
    },
  }
);

Deploy widget to CDN

Ship your own widget UI instead of the default chat bubble, using the SDK's deploy() / undeploy() methods on CopilotPlatform. Node.js only — run these from a build script or CI, never from the browser. They bundle your widget with esbuild and authenticate with your Boltic Personal Access Token (PAT).

esbuild required

deploy() and undeploy() depend on esbuild, which is not installed automatically. Install it once in your project:

npm install esbuild

If esbuild is missing, deploy() throws a clear error reminding you to install it.

Get your Boltic PAT

The PAT lets the SDK prove, from a script, that you own the agent you're deploying to.

1. Sign in to the Boltic platform at boltic.io.
2. Open Settings → Personal Access Tokens.
3. Generate a token, copy it, and store it as an env var: export BOLTIC_PAT="<your-token>". Never commit it or expose it in browser code.

Deploy

import { CopilotPlatform } from '@kaily-ai/chat-sdk';

const platform = CopilotPlatform.getInstance({
  environment: 'production',
  surfaceClient: 'web',
});

const cdnUrl = await platform.deploy('YOUR_KAILY_APP_TOKEN', './src/index.tsx', {
  pat: process.env.BOLTIC_PAT,
});

// embed anywhere: <script src={cdnUrl}></script>

Undeploy

// remove the custom widget — the agent reverts to the default Kaily widget
await platform.undeploy('YOUR_KAILY_APP_TOKEN', { pat: process.env.BOLTIC_PAT });

CSS limitation

caution

If you are using an AI assistant (LLM) to generate widget code, make sure it is aware of this.

deploy() supports plain CSS only. The following are not supported:

• Tailwind CSS (@tailwind utilities)
• PostCSS
• SASS / SCSS
• LESS

If your widget uses Tailwind or PostCSS, pre-process your CSS into plain CSS before calling deploy():

# pre-process Tailwind to plain CSS first
npx tailwindcss -i ./src/styles.css -o ./src/styles.output.css

// import the processed output, not the Tailwind source
import './styles.output.css'; // ✓
// import './styles.css';     // ✗ won't work with deploy()

Kaily Widget Starter (boilerplate)

Don't want to wire up the SDK from scratch? Kaily Widget Starter is a ready-made React + Vite skeleton built on top of @kaily-ai/chat-sdk. It comes with the chat UI, threads, file uploads, suggestions, feedback, and voice/video calls already wired in and toggled from one src/config.js file — you just drop in your bot token and customize.

npm install
# set token + serviceBaseUrl in src/config.js
npm run dev       # your local host link will be visible here
npm run deploy    # bundle + upload the widget to the Kaily CDN
npm run undeploy  # remove the deployed widget, revert to the default widget

npm run deploy / npm run undeploy are thin wrappers around the same platform.deploy() / platform.undeploy() calls described above.

Full API reference

The npm package README is the canonical reference for options, authentication, threads, tools, and types. Start here:

• Package README on npm

Choosing an integration path

Use @kaily-ai/chat-sdk when you want full control in TypeScript/JavaScript (custom UI, non-React stacks, or deep protocol access). Use the React Copilot Widget (@copilotlive/react-sdk) when you want a ready-made React chat UI.