Widget

JavaScript SDK

Control the Keva widget programmatically with the JavaScript SDK

The Keva Widget SDK provides methods to control the widget programmatically, respond to events, and integrate with your application logic.

Initialization

Initialize the widget with window.Keva.init():

const widget = window.Keva.init({
  apiKey: 'keva_live_your_api_key',
  apiUrl: 'https://app.keva.support', // Optional
  user: {
    email: 'customer@example.com',
    name: 'John Doe'
  }
});

Init Options

OptionTypeRequiredDescription
apiKeystringYesYour widget API key
apiUrlstringNoCustom API URL (for self-hosted)
user.emailstringNoPre-fill customer email
user.namestringNoPre-fill customer name

Widget Instance

After initialization, access the widget instance:

const widget = window.Keva.instance;

Methods

open()

Opens the chat panel.

window.Keva.instance.open();

close()

Closes the chat panel.

window.Keva.instance.close();

toggle()

Toggles the chat panel open/closed.

window.Keva.instance.toggle();

setUser(user)

Updates the user information. Call this when a user logs in.

window.Keva.instance.setUser({
  email: 'customer@example.com',
  name: 'John Doe'
});

destroy()

Removes the widget from the page and cleans up resources.

window.Keva.instance.destroy();

Event Handling

Subscribe to widget events with the on() method:

const unsubscribe = window.Keva.instance.on('messageSent', (data) => {
  console.log('Message sent:', data.message);
});
 
// Later: unsubscribe
unsubscribe();

Available Events

EventDataDescription
ready{ config }Widget loaded and configured
opennoneChat panel opened
closenoneChat panel closed
conversationStarted{ conversationId }New conversation created
messageSent{ message }Customer sent a message
messageReceived{ message }Agent message received
error{ error }An error occurred

Examples

Open Widget on Button Click

<button onclick="window.Keva.instance.open()">
  Need help?
</button>

Track Conversations in Analytics

window.Keva.instance.on('conversationStarted', ({ conversationId }) => {
  // Send to your analytics
  gtag('event', 'support_conversation_started', {
    conversation_id: conversationId
  });
});

Update User on Login

function onUserLogin(user) {
  window.Keva.instance.setUser({
    email: user.email,
    name: user.fullName
  });
}

Conditional Widget Display

// Only show widget for logged-in users
if (currentUser) {
  window.Keva.init({
    apiKey: 'keva_live_your_api_key',
    user: {
      email: currentUser.email,
      name: currentUser.name
    }
  });
}

Handle Errors

window.Keva.instance.on('error', ({ error }) => {
  console.error('Widget error:', error);
  // Optionally show fallback support option
});

Singleton Behavior

Only one widget instance can exist at a time. Calling init() again will destroy the existing instance and create a new one.

// First init
window.Keva.init({ apiKey: 'key1' });
 
// Second init destroys first, creates new
window.Keva.init({ apiKey: 'key2' });

TypeScript Support

Type definitions are included. Import types for your application:

interface KevaInitOptions {
  apiKey: string;
  apiUrl?: string;
  user?: { email?: string; name?: string };
}
 
interface KevaWidgetInstance {
  open(): void;
  close(): void;
  toggle(): void;
  destroy(): void;
  setUser(user: { email?: string; name?: string }): void;
  on(event: WidgetEvent, callback: (data: unknown) => void): () => void;
}
 
type WidgetEvent =
  | 'ready'
  | 'open'
  | 'close'
  | 'conversationStarted'
  | 'messageSent'
  | 'messageReceived'
  | 'error';