Skip to main content
The BubblaV SDK provides a global window.BubblaV object that allows you to control the widget and search interface programmatically, as well as listen for events.

​
SDK Availability

The SDK is available immediately after the script loads: 
window.BubblaV.on('message:received', (message) => {
  console.log('Message:', message);
});

​
Methods

​
BubblaV.open()

Opens the chat widget. 
window.BubblaV.open();

​
BubblaV.close()

Closes the chat widget. 
window.BubblaV.close();

​
BubblaV.toggle()

Toggles the chat widget open or closed. 
window.BubblaV.toggle();

​
BubblaV.openSearch()

Opens the search interface (modal). 
window.BubblaV.openSearch();

​
BubblaV.sendMessage(text, conversationId?)

Sends a message to the chatbot on behalf of the user.
  • text (string): The message content to send.
  • conversationId (string, optional): The ID of the conversation to send the message to. If provided, the widget switches to this conversation. If omitted, it sends to the active conversation or starts a new one.
// Send to active conversation (or start new if none)
window.BubblaV.sendMessage("Hello, I need help!");

// Send to specific conversation
window.BubblaV.sendMessage("Following up on this", "123e4567-e89b-12d3...");

​
BubblaV.showGreeting(message?)

Shows the greeting message bubble. Parameters:
  • message (optional): A custom greeting message to display. If omitted, the default greeting from your settings will be used.
// Show default greeting
window.BubblaV.showGreeting();

// Show custom greeting
window.BubblaV.showGreeting("Hello! Check out our new features.");

​
BubblaV.hideGreeting()

Hides the greeting message bubble. 
window.BubblaV.hideGreeting();

​
BubblaV.on(event, callback)

Subscribes to an event.
  • event (string): The name of the event to listen for.
  • callback (function): The function to call when the event occurs.
window.BubblaV.on('chat:opened', () => {
  console.log('Chat widget opened');
});

// Listen for all messages (visitor and bot)
window.BubblaV.on('message:received', (message) => {
  if (message.fromVisitor) {
    console.log('Visitor sent:', message);
  } else {
    console.log('Bot replied:', message);
    // Fetch suggestions when bot responds
    fetchSuggestions();
  }
});

​
BubblaV.off(event, callback)

Unsubscribes from an event. 
window.BubblaV.off('chat:opened', myCallback);

​
Events

You can listen to these events using BubblaV.on().
Event NameDescriptionPayload
chat:openedTriggered when the chat widget is opened.undefined
chat:closedTriggered when the chat widget is closed.undefined
search:openedTriggered when the search interface is opened.{ mode: string }
search:closedTriggered when the search interface is closed.{ mode: string }
message:sentTriggered when a message is sent by the user.{ conversation_id: string, text: string }
message:receivedTriggered when a message is received from the bot/agent.{ conversation_id: string, message_id: string, text: string, fromVisitor: boolean }
message:ratedTriggered when a specific message is rated.{ conversation_id: string, message_id: string, rating: 'up' | 'down' }
conversation:ratedTriggered when the conversation is rated.{ conversation_id: string, rating: number }
widget:expandedTriggered when the widget is expanded (desktop).undefined
widget:collapsedTriggered when the widget is collapsed (desktop).undefined
search:queryTriggered when a search query is submitted.{ query: string, source: "input" | "suggestion" }
readyTriggered when the widget is fully loaded.undefined