API Reference

The Koi Widget provides a comprehensive JavaScript API for programmatic control and integration with your application.

Global Object

The widget exposes a global KoiWidget object with the following methods:

1// Check if widget is loaded
2if (typeof KoiWidget !== 'undefined') {
3    // Widget is ready to use
4}
5

Core Methods

KoiWidget.open()

Opens the chat widget interface.

KoiWidget.open();

Returns: void

KoiWidget.close()

Closes the chat widget interface.

KoiWidget.close();

Returns: void

KoiWidget.toggle()

Toggles the chat widget interface (open/close).

KoiWidget.toggle();

Returns: void

KoiWidget.isOpen()

Checks if the chat widget is currently open.

const isOpen = KoiWidget.isOpen();
console.log('Widget is open:', isOpen);

Returns: boolean

Configuration Methods

KoiWidget.configure(options)

Updates widget configuration at runtime.

1KoiWidget.configure({
2    primaryColor: '#ff6b6b',
3    accentColor: '#4ecdc4',
4    position: 'bottom-left'
5});
6

Parameters:

  • options (Object): Configuration options to update

Returns: void

KoiWidget.getConfig()

Gets the current widget configuration.

const config = KoiWidget.getConfig();
console.log('Current config:', config);

Returns: Object - Current configuration

Messaging Methods

KoiWidget.sendMessage(message, options)

Sends a message programmatically.

1// Send a simple text message
2KoiWidget.sendMessage('Hello from the API!');
3
4// Send with options
5KoiWidget.sendMessage('Hello!', {
6    sender: 'system',
7    timestamp: new Date(),
8    metadata: { source: 'api' }
9});
10

Parameters:

  • message (string): Message text
  • options (Object, optional): Additional message options
    • sender (string): Message sender ('user' | 'bot' | 'system')
    • timestamp (Date): Message timestamp
    • metadata (Object): Additional metadata

Returns: Promise<void>

KoiWidget.clearMessages()

Clears all messages from the chat.

KoiWidget.clearMessages();

Returns: void

KoiWidget.getMessages()

Gets all messages from the current conversation.

const messages = KoiWidget.getMessages();
console.log('All messages:', messages);

Returns: Array<Message> - Array of message objects

KoiWidget.setWelcomeMessage(message)

Updates the welcome message.

KoiWidget.setWelcomeMessage('Welcome back! How can we help you today?');

Parameters:

  • message (string): New welcome message

Returns: void

Quick Actions

KoiWidget.setQuickActions(actions)

Updates the quick action buttons.

1KoiWidget.setQuickActions([
2    { label: 'Get Pricing', message: 'What are your pricing plans?' },
3    { label: 'Book Demo', message: 'I would like to schedule a demo' },
4    { label: 'Support', message: 'I need technical support' }
5]);
6

Parameters:

  • actions (Array): Array of quick action objects
    • label (string): Button label
    • message (string): Message to send when clicked

Returns: void

KoiWidget.addQuickAction(action)

Adds a single quick action button.

1KoiWidget.addQuickAction({
2    label: 'New Action',
3    message: 'This is a new quick action'
4});
5

Parameters:

  • action (Object): Quick action object

Returns: void

KoiWidget.removeQuickAction(label)

Removes a quick action by label.

KoiWidget.removeQuickAction('Get Pricing');

Parameters:

  • label (string): Label of the action to remove

Returns: void

User Management

KoiWidget.setUser(user)

Sets the current user information.

1KoiWidget.setUser({
2    id: 'user-123',
3    name: 'John Doe',
4    email: 'john@example.com',
5    avatar: 'https://example.com/avatar.jpg',
6    metadata: {
7        plan: 'premium',
8        signupDate: '2024-01-15'
9    }
10});
11

Parameters:

  • user (Object): User information
    • id (string): Unique user ID
    • name (string, optional): User's name
    • email (string, optional): User's email
    • avatar (string, optional): Avatar URL
    • metadata (Object, optional): Additional user data

Returns: void

KoiWidget.getUser()

Gets the current user information.

const user = KoiWidget.getUser();
console.log('Current user:', user);

Returns: Object | null - User object or null if not set

KoiWidget.clearUser()

Clears the current user information.

KoiWidget.clearUser();

Returns: void

Session Management

KoiWidget.startSession(sessionId)

Starts a new chat session.

KoiWidget.startSession('session-abc-123');

Parameters:

  • sessionId (string, optional): Custom session ID

Returns: string - Session ID

KoiWidget.endSession()

Ends the current chat session.

KoiWidget.endSession();

Returns: void

KoiWidget.getSessionId()

Gets the current session ID.

const sessionId = KoiWidget.getSessionId();
console.log('Session ID:', sessionId);

Returns: string | null

File Upload

KoiWidget.uploadFile(file, options)

Uploads a file programmatically.

1const fileInput = document.getElementById('file-input');
2const file = fileInput.files[0];
3
4KoiWidget.uploadFile(file, {
5    onProgress: (progress) => {
6        console.log('Upload progress:', progress);
7    },
8    onComplete: (result) => {
9        console.log('Upload complete:', result);
10    },
11    onError: (error) => {
12        console.error('Upload error:', error);
13    }
14});
15

Parameters:

  • file (File): File object to upload
  • options (Object, optional): Upload options
    • onProgress (Function): Progress callback
    • onComplete (Function): Success callback
    • onError (Function): Error callback

Returns: Promise<Object> - Upload result

Event System

KoiWidget.on(event, callback)

Subscribes to widget events.

1// Listen for widget open/close
2KoiWidget.on('open', () => {
3    console.log('Widget opened');
4});
5
6KoiWidget.on('close', () => {
7    console.log('Widget closed');
8});
9
10// Listen for messages
11KoiWidget.on('message', (message) => {
12    console.log('New message:', message);
13});
14
15// Listen for user interactions
16KoiWidget.on('quickAction', (action) => {
17    console.log('Quick action clicked:', action);
18});
19

Parameters:

  • event (string): Event name
  • callback (Function): Event handler

Returns: void

KoiWidget.off(event, callback)

Unsubscribes from widget events.

1const messageHandler = (message) => {
2    console.log('Message:', message);
3};
4
5// Subscribe
6KoiWidget.on('message', messageHandler);
7
8// Unsubscribe
9KoiWidget.off('message', messageHandler);
10

Parameters:

  • event (string): Event name
  • callback (Function): Event handler to remove

Returns: void

KoiWidget.emit(event, data)

Emits a custom event.

KoiWidget.emit('customEvent', { data: 'custom data' });

Parameters:

  • event (string): Event name
  • data (any): Event data

Returns: void

Available Events

Widget Events

  • ready - Widget is loaded and ready
  • open - Widget interface opened
  • close - Widget interface closed
  • resize - Widget resized

Message Events

  • message - New message received
  • messageSent - Message sent by user
  • typing - Typing indicator changed
  • messageRead - Message marked as read

User Events

  • userSet - User information updated
  • userCleared - User information cleared
  • quickAction - Quick action button clicked

File Events

  • fileUpload - File upload started
  • fileUploaded - File upload completed
  • fileError - File upload error

Session Events

  • sessionStart - New session started
  • sessionEnd - Session ended
  • sessionUpdate - Session data updated

Utility Methods

KoiWidget.isSupported()

Checks if the current browser supports the widget.

1if (KoiWidget.isSupported()) {
2    console.log('Widget is supported');
3} else {
4    console.log('Widget is not supported');
5}
6

Returns: boolean

KoiWidget.getVersion()

Gets the widget version.

const version = KoiWidget.getVersion();
console.log('Widget version:', version);

Returns: string

KoiWidget.destroy()

Completely removes the widget from the page.

KoiWidget.destroy();

Returns: void

Error Handling

The widget API includes comprehensive error handling:

1try {
2    await KoiWidget.sendMessage('Hello!');
3} catch (error) {
4    console.error('Failed to send message:', error);
5}
6
7// Or use error events
8KoiWidget.on('error', (error) => {
9    console.error('Widget error:', error);
10});
11

TypeScript Support

The widget includes TypeScript definitions:

1interface KoiWidgetConfig {
2    primaryColor?: string;
3    accentColor?: string;
4    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
5    // ... other options
6}
7
8interface KoiWidgetAPI {
9    open(): void;
10    close(): void;
11    toggle(): void;
12    configure(options: Partial<KoiWidgetConfig>): void;
13    // ... other methods
14}
15
16declare global {
17    interface Window {
18        KoiWidget: KoiWidgetAPI;
19    }
20}
21

Complete Example

Here's a comprehensive example using the API:

1// Wait for widget to load
2KoiWidget.on('ready', () => {
3    console.log('Widget is ready!');
4    
5    // Set user information
6    KoiWidget.setUser({
7        id: 'user-123',
8        name: 'John Doe',
9        email: 'john@example.com'
10    });
11    
12    // Configure widget
13    KoiWidget.configure({
14        primaryColor: '#2563eb',
15        welcomeMessage: 'Welcome back, John!'
16    });
17    
18    // Set up event listeners
19    KoiWidget.on('message', (message) => {
20        console.log('New message:', message);
21        
22        // Send to analytics
23        analytics.track('chat_message', {
24            sessionId: KoiWidget.getSessionId(),
25            messageLength: message.text.length
26        });
27    });
28    
29    // Auto-open for returning users
30    if (localStorage.getItem('returning_user')) {
31        setTimeout(() => {
32            KoiWidget.open();
33        }, 2000);
34    }
35});
36
37// Handle errors
38KoiWidget.on('error', (error) => {
39    console.error('Widget error:', error);
40    // Report to error tracking service
41});
42

For more examples and advanced usage, see our examples section or contact support.