SDK Reference

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. For React, Vue, and Angular projects, we recommend using our NPM packages for better type safety and framework integration.

Installation

NPM Packages (Recommended)

For framework projects, use our official NPM packages:

React
Vue
Angular

1. Install the package:

npm install @bubblav/ai-chatbot-react

2. Add the widget to your app:

import { BubblaVWidget } from '@bubblav/ai-chatbot-react';

function App() {
  return (
    <BubblaVWidget websiteId="your-website-id" />
  );
}

3. Control the widget programmatically:

import { useBubblaVWidget } from '@bubblav/ai-chatbot-react';

function MyComponent() {
  const widget = useBubblaVWidget();

  const handleSupportClick = () => {
    widget?.open();
    widget?.sendMessage('Hello! I need help.');
  };

  return <button onClick={handleSupportClick}>Get Support</button>;
}

1. Install the package:

npm install @bubblav/ai-chatbot-vue

2. Add the widget to your app:

<script setup>
import { BubblaVWidget } from '@bubblav/ai-chatbot-vue';
</script>

<template>
  <BubblaVWidget website-id="your-website-id" />
</template>

3. Control the widget programmatically:

<script setup>
import { useBubblaVWidget } from '@bubblav/ai-chatbot-vue';

const widget = useBubblaVWidget();

const handleSupportClick = () => {
  widget?.open();
  widget?.sendMessage('Hello! I need help.');
};
</script>

<template>
  <button @click="handleSupportClick">Get Support</button>
</template>

1. Install the package:

npm install @bubblav/ai-chatbot-angular

2. Add the widget to your app:

import { Component } from '@angular/core';
import { BubblaVWidgetComponent } from '@bubblav/ai-chatbot-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [BubblaVWidgetComponent],
  template: `<bubblav-widget websiteId="your-website-id" />`
})
export class AppComponent {}

3. Control the widget programmatically:

import { Component, inject } from '@angular/core';
import { BubblaVWidgetService } from '@bubblav/ai-chatbot-angular';

@Component({
  selector: 'app-support',
  template: `<button (click)="handleSupportClick()">Get Support</button>`
})
export class SupportComponent {
  private bubblav = inject(BubblaVWidgetService);

  handleSupportClick() {
    this.bubblav.open();
    this.bubblav.sendMessage('Hello! I need help.');
  }
}

NPM packages provide full TypeScript support, framework-specific patterns, and better lifecycle management.

Global SDK

For vanilla JavaScript or when not using a framework, the SDK is available as window.BubblaV:

// Check if SDK is ready
if (window.BubblaV) {
  window.BubblaV.open();
}

// Or use the ready callback
window.BubblaV.ready(() => {
  window.BubblaV.sendMessage('Hello!');
});

The SDK may not be available immediately. Use the ready() callback to ensure it’s loaded.

SDK Methods

`open()`

Opens the chat widget.

BubblaV.open();

Use cases:

Trigger chat from a custom button
Open chat after a user action
Start conversation proactively

`close()`

Closes the chat widget.

BubblaV.close();

Use cases:

Close chat after a conversation
Respond to user dismiss action

`toggle()`

Toggles the widget open/closed state.

BubblaV.toggle();

Use cases:

Single button to toggle widget
Keyboard shortcuts for chat access

`openSearch()`

Opens the search interface (modal).

BubblaV.openSearch();

Use cases:

Trigger search from a custom button
Open search after a user action

`isOpen()`

Checks if the widget is currently open.

if (BubblaV.isOpen()) {
  console.log('Widget is open');
}

Returns: 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

Use cases:

Start conversation with a suggested message
Send contextual help based on page content
Pre-fill messages based on user actions

`showGreeting(data)`

Shows a greeting message to the user with optional sender information.

// Show default greeting
BubblaV.showGreeting();

// Show custom message
BubblaV.showGreeting('Hi! How can I help you today?');

// Show greeting with sender info
BubblaV.showGreeting({
  message: 'Hi! How can I help you today?',
  senderName: 'Support Team',
  senderAvatarUrl: 'https://example.com/avatar.png',
  timestamp: new Date().toISOString()
});

Parameter	Type	Required	Description
`data`	`string` \| `object`	No	Message string or object with `message`, `senderName`, `senderAvatarUrl`, `timestamp`

Use cases:

Display contextual greetings based on page
Show agent-specific messages with avatar
Time-based greetings (good morning, etc.)
Campaign-specific messages

`hideGreeting()`

Hides the greeting message.

BubblaV.hideGreeting();

Configuration

`getConfig()`

Gets the current widget configuration.

const config = BubblaV.getConfig();
console.log('Widget config:', config);

Returns: 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)`

BubblaV.on('chat:opened', () => {
  console.log('Chat widget opened');
});

BubblaV.on('message:received', (message) => {
  console.log('New message:', message);
});

`off(event, callback)`

Unregister an event listener.

const handler = () => console.log('Chat opened');

BubblaV.on('chat:opened', handler);
// Later...
BubblaV.off('chat:opened', handler);

Available Events

Event	Description	Payload
`chat:opened`	Triggered when the chat widget is opened.	`undefined`
`chat:closed`	Triggered when the chat widget is closed.	`undefined`
`search:opened`	Triggered when the search interface is opened.	`{ mode: string }`
`search:closed`	Triggered when the search interface is closed.	`{ mode: string }`
`message:sent`	Triggered when a message is sent by the user.	`{ conversation_id: string, text: string }`
`message:received`	Triggered when a message is received from the bot/agent.	`{ conversation_id: string, message_id: string, text: string, fromVisitor: boolean }`
`message:rated`	Triggered when a specific message is rated.	`{ conversation_id: string, message_id: string, rating: 'up' \| 'down' }`
`conversation:rated`	Triggered when the conversation is rated.	`{ conversation_id: string, rating: number }`
`widget:expanded`	Triggered when the widget is expanded (desktop).	`undefined`
`widget:collapsed`	Triggered when the widget is collapsed (desktop).	`undefined`
`search:query`	Triggered when a search query is submitted.	`{ query: string, source: "input" \| "suggestion" }`
`ready`	Triggered when the widget is fully loaded.	`undefined`

Framework Examples

React

Using Hooks

'use client';

import { useRef } from 'react';
import { BubblaVWidget, useBubblaVWidget, useBubblaVEvent } from '@bubblav/ai-chatbot-react';
import type { BubblaVWidgetRef } from '@bubblav/ai-chatbot-react';

function SupportButton() {
  const widgetRef = useRef<BubblaVWidgetRef>(null);
  const widget = useBubblaVWidget();

  // Listen to events
  useBubblaVEvent('chat:opened', () => {
    console.log('Support chat opened');
  });

  const openSupport = () => {
    widget?.open();
  };

  return (
    <>
      <button onClick={openSupport}>Get Support</button>
      <BubblaVWidget ref={widgetRef} websiteId="your-website-id" />
    </>
  );
}

import { BubblaVWidget } from '@bubblav/ai-chatbot-react';

function App() {
  return (
    <BubblaVWidget
      websiteId="your-website-id"
      bubbleColor="#3b82f6"
      position="bottom-right"
    />
  );
}

Vue

Using Composition API

<script setup>
import { ref } from 'vue';
import { BubblaVWidget, useBubblaVWidget, useBubblaVEvent } from '@bubblav/ai-chatbot-vue';

const widgetRef = ref(null);
const widget = useBubblaVWidget();

// Listen to events
useBubblaVEvent('chat:opened', () => {
  console.log('Support chat opened');
});

const openSupport = () => {
  widget?.open();
};
</script>

<template>
  <button @click="openSupport">Get Support</button>
  <BubblaVWidget ref="widgetRef" website-id="your-website-id" />
</template>

Using Options API

<script>
import { BubblaVWidget } from '@bubblav/ai-chatbot-vue';

export default {
  components: { BubblaVWidget },
  methods: {
    openSupport() {
      this.$bubblav.open();
    }
  }
};
</script>

<template>
  <button @click="openSupport">Get Support</button>
  <BubblaVWidget website-id="your-website-id" />
</template>

Angular

import { Component, inject } from '@angular/core';
import { BubblaVWidgetComponent, BubblaVWidgetService } from '@bubblav/ai-chatbot-angular';

@Component({
  selector: 'app-support',
  standalone: true,
  imports: [BubblaVWidgetComponent],
  template: `
    <button (click)="openSupport()">Get Support</button>
    <bubblav-widget websiteId="your-website-id" />
  `
})
export class SupportComponent {
  private bubblav = inject(BubblaVWidgetService);

  constructor() {
    // Listen to events
    this.bubblav.on('chat:opened', () => {
      console.log('Support chat opened');
    });
  }

  openSupport() {
    this.bubblav.open();
  }
}

TypeScript Support

All NPM packages include full TypeScript definitions:

import type {
  BubblaVWidgetProps,
  BubblaVWidgetRef,
  BubblaVSDK,
  BubblaVEvent
} from '@bubblav/ai-chatbot-react';

// Full type safety
const config: BubblaVWidgetProps = {
  websiteId: 'your-website-id',
  bubbleColor: '#3b82f6',
  position: 'bottom-right'
};

// Type-safe event listeners
const eventHandler: BubblaVEvent<'chat:opened'> = () => {
  console.log('Chat opened');
};

Best Practices

Prefer NPM Packages For React, Vue, and Angular projects, use the NPM packages instead of the global SDK for better type safety and lifecycle management.
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('chat:opened', handler);
// Later...
BubblaV.off('chat:opened', handler);

Handle Edge Cases Check if methods exist before calling:

if (BubblaV && typeof BubblaV.open === 'function') {
  BubblaV.open();
}

Use Environment Variables Store your website ID in environment variables:

# Next.js
NEXT_PUBLIC_BUBBLAV_WEBSITE_ID=your-website-id

# Nuxt
NUXT_PUBLIC_BUBBLAV_WEBSITE_ID=your-website-id

<BubblaVWidget websiteId={process.env.NEXT_PUBLIC_BUBBLAV_WEBSITE_ID} />

Full SDK Reference

interface BubblaVSDK {
  // Widget control
  open(): void;
  close(): void;
  toggle(): void;
  openSearch(): void;
  isOpen(): boolean;

  // Messaging
  sendMessage(text: string, conversationId?: string): void;
  showGreeting(data: string | { message?: string; senderName?: string; senderAvatarUrl?: string; timestamp?: 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;
}

Installation

NPM Packages (Recommended)

Global SDK

SDK Methods

Widget Control

`open()`

`close()`

`toggle()`

`openSearch()`

`isOpen()`

Messaging

`sendMessage(text, conversationId?)`

`showGreeting(data)`

`hideGreeting()`

Configuration

`getConfig()`

`setDebug(enabled)`

Event System

`on(event, callback)`

`off(event, callback)`

Available Events

Framework Examples

React

Using Hooks

Using the Widget Component

Vue

Using Composition API

Using Options API

Angular

TypeScript Support

Best Practices

Full SDK Reference

Next Steps

Widget Design

Starter Templates

​Installation

​NPM Packages (Recommended)

​Global SDK

​SDK Methods

​Widget Control

​open()

​close()

​toggle()

​openSearch()

​isOpen()

​Messaging

​sendMessage(text, conversationId?)

​showGreeting(data)

​hideGreeting()

​Configuration

​getConfig()

​setDebug(enabled)

​Event System

​on(event, callback)

​off(event, callback)

​Available Events

​Framework Examples

​React

​Using Hooks

​Using the Widget Component

​Vue

​Using Composition API

​Using Options API

​Angular

​TypeScript Support

​Best Practices

​Full SDK Reference

​Next Steps

Widget Design

Starter Templates

Installation

NPM Packages (Recommended)

Global SDK

SDK Methods

Widget Control

`open()`

`close()`

`toggle()`

`openSearch()`

`isOpen()`

Messaging

`sendMessage(text, conversationId?)`

`showGreeting(data)`

`hideGreeting()`

Configuration

`getConfig()`

`setDebug(enabled)`

Event System

`on(event, callback)`

`off(event, callback)`

Available Events

Framework Examples

React

Using Hooks

Using the Widget Component

Vue

Using Composition API

Using Options API

Angular

TypeScript Support

Best Practices

Full SDK Reference

Next Steps