Widget Control

Programmatically control your chat widget with JavaScript methods to open, close, and reset conversations.

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

Methods

open()

Opens the chat widget.

window.chatbase.open();

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();
});

Time-Based Reset

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

Reset After 5 Minutes of Inactivity

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);

Reset After Tool Completion

After Transaction

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);
  }
});

Reset on Keywords

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

User Says Goodbye

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);
  }
});

Reset on Navigation

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

Single-Page App

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();

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