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 textoptions
(Object, optional): Additional message optionssender
(string): Message sender ('user' | 'bot' | 'system')timestamp
(Date): Message timestampmetadata
(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 objectslabel
(string): Button labelmessage
(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 informationid
(string): Unique user IDname
(string, optional): User's nameemail
(string, optional): User's emailavatar
(string, optional): Avatar URLmetadata
(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 uploadoptions
(Object, optional): Upload optionsonProgress
(Function): Progress callbackonComplete
(Function): Success callbackonError
(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 namecallback
(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 namecallback
(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 namedata
(any): Event data
Returns: void
Available Events
Widget Events
ready
- Widget is loaded and readyopen
- Widget interface openedclose
- Widget interface closedresize
- Widget resized
Message Events
message
- New message receivedmessageSent
- Message sent by usertyping
- Typing indicator changedmessageRead
- Message marked as read
User Events
userSet
- User information updateduserCleared
- User information clearedquickAction
- Quick action button clicked
File Events
fileUpload
- File upload startedfileUploaded
- File upload completedfileError
- File upload error
Session Events
sessionStart
- New session startedsessionEnd
- Session endedsessionUpdate
- 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.