Widget Control

The Chatbase embed script exposes the window.chatbase object with methods to control your chat widget programmatically.

Methods

open(options?)

Opens the chat widget. Optionally sends a message when it opens.

window.chatbase.open();

Parameters

options.message

string

A message to send automatically when the widget opens.

options.hideMessage

boolean

default:"false"

When true, the sent message is hidden and the widget stays closed until the bot starts replying — so it looks like the assistant reached out proactively. Only applies when message is set.

window.chatbase.open({ message: "What is Chatbase's pricing?" });

window.chatbase.open({
  message: "What is Chatbase's pricing?",
  hideMessage: true,
});

close()

Closes the chat widget.

window.chatbase.close();

resetChat()

Clears the current conversation and starts a new session.

window.chatbase.resetChat();

Your widget configuration and custom initial messages are preserved after reset.

Examples

Combine these methods with event listeners to build powerful, context-aware chat experiences.

Custom Buttons

Trigger widget actions from your own UI elements:

document.getElementById("help-button").addEventListener("click", () => {
  window.chatbase.open();
});

document.getElementById("close-button").addEventListener("click", () => {
  window.chatbase.close();
});

document.getElementById("new-chat-button").addEventListener("click", () => {
  window.chatbase.resetChat();
});

Answer FAQ Questions

Turn static FAQ entries into live answers — open the widget with the question pre-filled:

document.querySelectorAll(".faq-question").forEach((item) => {
  item.addEventListener("click", () => {
    window.chatbase.open({ message: item.dataset.question });
  });
});

Proactive Message on Intent

Reach out automatically when a visitor lingers on a high-intent page. The message is hidden until the bot replies, so it feels like the assistant started the conversation.

// On the /pricing page: if the user hasn't acted after 10 minutes, reach out
setTimeout(() => {
  window.chatbase.open({
    message: "Do you have any questions about our pricing?",
    hideMessage: true,
  });
}, 10 * 60 * 1000);

Time-Based Reset

The 24-hour example uses localStorage to persist the last message time across page reloads.

let inactivityTimer;

function startInactivityTimer() {
  clearTimeout(inactivityTimer);
  inactivityTimer = setTimeout(
    () => window.chatbase.resetChat(),
    5 * 60 * 1000
  );
}

window.chatbase.addEventListener("user-message", startInactivityTimer);
window.chatbase.addEventListener("assistant-message", startInactivityTimer);

const STORAGE_KEY = "chatbase_last_message";
const TWENTY_FOUR_HOURS = 24 * 60 * 60 * 1000;

function updateLastMessageTime() {
  localStorage.setItem(STORAGE_KEY, Date.now().toString());
}

// Check on page load
const lastMessage = localStorage.getItem(STORAGE_KEY);
if (lastMessage && Date.now() - parseInt(lastMessage) > TWENTY_FOUR_HOURS) {
  window.chatbase.resetChat();
  updateLastMessageTime(); // Reset the timer after clearing
}

// Update timestamp on every message
window.chatbase.addEventListener("user-message", updateLastMessageTime);
window.chatbase.addEventListener("assistant-message", updateLastMessageTime);

Reset After Tool Completion

let resetTimer;

window.chatbase.addEventListener("tool-result", (event) => {
  const resetTools = ["complete-booking", "process-payment", "create-ticket"];

  if (resetTools.includes(event.data.name) && event.data.result?.success) {
    clearTimeout(resetTimer);
    // 2 second delay before resetting the chat
    resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
  }
});

let resetTimer;

window.chatbase.addEventListener("tool-result", (event) => {
  if (event.data.name === "create-ticket") {
    clearTimeout(resetTimer);
    // 2 second delay before resetting the chat
    resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
  }
});

Reset on Keywords

Always add a delay before resetting so users can read the final AI response.

let resetTimer;

window.chatbase.addEventListener("user-message", (event) => {
  const goodbyePhrases = ["goodbye", "bye", "that's all", "start over"];
  const message = event.data.content.toLowerCase();

  // Use word boundaries to avoid matching substrings (e.g., "nearby" containing "bye")
  const matchesPhrase = goodbyePhrases.some((phrase) => {
    const regex = new RegExp(`\\b${phrase}\\b`);
    return regex.test(message);
  });

  if (matchesPhrase) {
    clearTimeout(resetTimer);
    // 2 second delay before resetting the chat
    resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
  }
});

let resetTimer;

window.chatbase.addEventListener("assistant-message", (event) => {
  const donePhrases = ["order confirmed", "booking complete", "ticket created"];
  const message = event.data.content.toLowerCase();

  const matchesPhrase = donePhrases.some((phrase) => {
    const regex = new RegExp(`\\b${phrase}\\b`);
    return regex.test(message);
  });

  if (matchesPhrase) {
    clearTimeout(resetTimer);
    // 2 second delay before resetting the chat
    resetTimer = setTimeout(() => window.chatbase.resetChat(), 2000);
  }
});

Start fresh conversations when users enter specific sections of your site.

const resetOnRoutes = ["/checkout", "/new-project", "/support"];

function checkRouteAndReset() {
  if (resetOnRoutes.includes(window.location.pathname)) {
    window.chatbase.resetChat();
  }
}

// Call this from your router's navigation callback
// e.g., router.afterEach(checkRouteAndReset)
checkRouteAndReset();

// Add this script to pages where you want fresh conversations
window.chatbase.resetChat();

Best Practices

Debounce rapid calls — Avoid calling methods in quick succession
Add delays before reset — Give users time to read the final response
Respect dismissals — Don’t immediately reopen a closed widget
Use contextual triggers — Open chat at moments when help is most relevant

Next Steps

Event Listeners

Learn to listen for and respond to chat events in real-time

Custom Initial Messages

Create dynamic, personalized initial messages for users

Floating Initial Messages

Display floating messages over the chat bubble

Getting Started

JavaScript Embed Features

API v1 Reference

Advanced Integration

Widgets

Methods

open(options?)

close()

resetChat()

Examples

Custom Buttons

Answer FAQ Questions

Proactive Message on Intent

Time-Based Reset

Reset After Tool Completion

Reset on Keywords

Reset on Navigation

Best Practices

Next Steps

Event Listeners

Custom Initial Messages

Floating Initial Messages

​Methods

​open(options?)

​close()

​resetChat()

​Examples

​Custom Buttons

​Answer FAQ Questions

​Proactive Message on Intent

​Time-Based Reset

​Reset After Tool Completion

​Reset on Keywords

​Reset on Navigation

​Best Practices

​Next Steps

Event Listeners

Custom Initial Messages

Floating Initial Messages

Methods

open(options?)

close()

resetChat()

Examples

Custom Buttons

Answer FAQ Questions

Proactive Message on Intent

Time-Based Reset

Reset After Tool Completion

Reset on Keywords

Reset on Navigation

Best Practices

Next Steps