The BubblaV SDK provides programmatic control over your chat widget. Use it to open/close the widget, send messages, listen to events, and more.
The SDK is automatically loaded when you add the widget to your site. It’s available as window.BubblaV or via framework-specific packages.
Installation
Choose your preferred method:
Using NPM Packages
React:npm install @bubblav/ai-chatbot-react
import { useBubblaVWidget } from '@bubblav/ai-chatbot-react';
const widget = useBubblaVWidget();
widget?.sendMessage('Hello!');
npm install @bubblav/ai-chatbot-vue
<script setup>
import { useBubblaVWidget } from '@bubblav/ai-chatbot-vue';
const widget = useBubblaVWidget();
</script>
npm install @bubblav/ai-chatbot-angular
constructor(private bubblav: BubblaVWidgetService) {
bubblav.sendMessage('Hello!');
}
NPM packages provide full TypeScript support and framework-specific patterns.
Using Global SDK
The SDK is automatically available as window.BubblaV after the widget loads:// Check if SDK is ready
if (window.BubblaV) {
window.BubblaV.open();
}
// Or use the ready callback
window.BubblaV.ready(() => {
window.BubblaV.open();
});
The SDK may not be available immediately. Use the ready() callback to ensure it’s loaded.
SDK Methods
open()
Opens the chat widget.
Use cases:
- Trigger chat from a custom button
- Open chat after a user action
- Start conversation proactively
close()
Closes the chat widget.
Use cases:
- Close chat after a conversation
- Respond to user dismiss action
toggle()
Toggles the widget open/closed state.
Use cases:
- Single button to toggle widget
- Keyboard shortcuts for chat access
isOpen()
Checks if the widget is currently open.
if (BubblaV.isOpen()) {
console.log('Widget is open');
}
boolean
Messaging
sendMessage(text, conversationId?)
Sends a message programmatically.
// Send a simple message
BubblaV.sendMessage('Hello, I need help!');
// Send to a specific conversation
BubblaV.sendMessage('Where is my order?', 'conv_123');
| Parameter | Type | Required | Description |
|---|
text | string | Yes | Message text to send |
conversationId | string | No | Target conversation ID |
- Start conversation with a suggested message
- Send contextual help based on page content
- Pre-fill messages based on user actions
showGreeting(message?)
Shows a greeting message to the user.
// Show default greeting
BubblaV.showGreeting();
// Show custom greeting
BubblaV.showGreeting('Hi! How can I help you today?');
- Display contextual greetings based on page
- Time-based greetings (good morning, etc.)
- Campaign-specific messages
hideGreeting()
Hides the greeting message.
Configuration
getConfig()
Gets the current widget configuration.
const config = BubblaV.getConfig();
console.log('Widget config:', config);
object with current configuration
setDebug(enabled)
Enables or disables debug mode.
// Enable debug mode
BubblaV.setDebug(true);
// Disable debug mode
BubblaV.setDebug(false);
Only enable debug mode in development. It logs detailed information to the console.
Event System
The SDK emits events for various widget actions. Listen to events to respond to user interactions.
on(event, callback)
Register an event listener.
BubblaV.on('widget_opened', () => {
console.log('Widget was opened');
});
BubblaV.on('message:received', (message) => {
console.log('New message:', message);
});
off(event, callback)
Unregister an event listener.
const handler = () => console.log('Widget opened');
BubblaV.on('widget_opened', handler);
// Later...
BubblaV.off('widget_opened', handler);
Available Events
| Event | Description | Payload |
|---|
widget_opened | Widget was opened | None |
widget_closed | Widget was closed | None |
message:received | New message received | Message object |
message:sent | Message was sent | Message object |
conversation:started | New conversation started | Conversation ID |
visitor:identified | Visitor was identified | Visitor data |
Framework Examples
React
import { useEffect, useRef } from 'react';
import { BubblaVWidget, useBubblaVEvent, type BubblaVWidgetRef } from '@bubblav/ai-chatbot-react';
function SupportButton() {
const widgetRef = useRef<BubblaVWidgetRef>(null);
// Listen to events
useBubblaVEvent('widget_opened', () => {
console.log('Support chat opened');
});
const openSupport = () => {
widgetRef.current?.open();
};
return (
<>
<button onClick={openSupport}>Get Support</button>
<BubblaVWidget ref={widgetRef} websiteId="your-id" />
</>
);
}
Vue
<script setup>
import { ref } from 'vue';
import { BubblaVWidget, useBubblaVEvent } from '@bubblav/ai-chatbot-vue';
const widgetRef = ref(null);
// Listen to events
useBubblaVEvent('widget_opened', () => {
console.log('Support chat opened');
});
const openSupport = () => {
widgetRef.value?.open();
};
</script>
<template>
<button @click="openSupport">Get Support</button>
<BubblaVWidget ref="widgetRef" website-id="your-id" />
</template>
Angular
import { Component, inject, ref } from '@angular/core';
import { BubblaVWidgetService } from '@bubblav/ai-chatbot-angular';
@Component({
selector: 'app-support',
template: `
<button (click)="openSupport()">Get Support</button>
<bubblav-widget websiteId="your-id" />
`
})
export class SupportComponent {
private bubblav = inject(BubblaVWidgetService);
constructor() {
// Listen to events
this.bubblav.on('widget_opened', () => {
console.log('Support chat opened');
});
}
openSupport() {
this.bubblav.open();
}
}
TypeScript Support
All NPM packages include full TypeScript definitions:
import type {
BubblaVWidgetProps,
BubblaVWidgetRef,
BubblaVSDK
} from '@bubblav/ai-chatbot-react';
// Full type safety
const config: BubblaVWidgetProps = {
websiteId: 'your-id',
bubbleColor: '#3b82f6'
};
Best Practices
-
Wait for Ready State
Always check if the SDK is ready before using it:
BubblaV.ready(() => {
BubblaV.open();
});
-
Clean Up Listeners
Remove event listeners when they’re no longer needed:
const handler = () => console.log('Opened');
BubblaV.on('widget_opened', handler);
// Later...
BubblaV.off('widget_opened', handler);
-
Use Framework Packages
For React/Vue/Angular, use the NPM packages instead of the global SDK for better type safety and lifecycle management.
-
Handle Edge Cases
Check if methods exist before calling:
if (BubblaV && typeof BubblaV.open === 'function') {
BubblaV.open();
}
Full SDK Reference
interface BubblaVSDK {
// Widget control
open(): void;
close(): void;
toggle(): void;
isOpen(): boolean;
// Messaging
sendMessage(text: string, conversationId?: string): void;
showGreeting(message?: string): void;
hideGreeting(): void;
// Configuration
getConfig(): Record<string, unknown>;
setDebug(enabled: boolean): void;
// Events
on(event: string, callback: (...args: unknown[]) => void): void;
off(event: string, callback: (...args: unknown[]) => void): void;
emit(event: string, data?: unknown): void;
// Lifecycle
ready(callback: () => void): void;
// Analytics
track(eventName: string, properties?: Record<string, unknown>): void;
}
Next Steps
