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

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.