Chat bubble Control

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

Methods

open(options?)

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

window.chatbase.open();

Parameters

string

A message to send automatically when the chat bubble opens.

boolean

default:"false"

When true, the sent message is hidden and the chat bubble 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 bubble.

window.chatbase.close();

resetChat()

Clears the current conversation and starts a new session.

window.chatbase.resetChat();

Your chat bubble configuration and custom initial messages are preserved after reset.

Runtime Options

Override a bounded set of your agent’s configured options for the current page load — the chat bubble’s display name, footer, message placeholder, dismissible notice, initial messages, and suggested messages. Overrides are never persisted: reloading the page or calling resetOptions returns the chat bubble to its dashboard configuration.

setOptions(options)

window.chatbase.setOptions({
  displayName: "Acme Support",
  footer: "Powered by Acme",
  messagePlaceholder: "Ask us anything…",
  dismissibleNotice: "Chats may be recorded for quality purposes.",
  initialMessages: ["Hi!", "How can I help you today?"],
  suggestedMessages: ["Track my order", "Talk to a human"],
});

All keys are optional — pass only the ones you want to override. Parameters

string

Overrides the chat bubble header title. Also updates the launcher button’s accessibility labels so assistive technology announces the same name. Maximum 100 characters.

string

Overrides the footer text. Maximum 1000 characters.

string

Overrides the message input placeholder. Maximum 100 characters.

string

Overrides the dismissible notice shown above the message input. Maximum 500 characters.

string[]

Overrides the agent’s initial messages. Array of non-empty strings, limited to 1000 characters in total. Applies immediately if the conversation hasn’t started; otherwise it takes effect on the next fresh conversation (for example after resetChat()). Writes the same setting as setInitialMessages — the last call wins, whichever method made it.

string[]

Replaces the dashboard-configured suggested message chips. Up to 4 entries, each a non-empty string of at most 200 characters. Suggestions the AI generates during the conversation still take precedence over this override.

Invalid keys or values are skipped with a console.error; valid keys in the same call still apply. setOptions never truncates — an oversize value is rejected. (The legacy setInitialMessages method instead truncates to 1000 characters, preserving its documented behavior.)

resetOptions(fields?)

Clears runtime overrides, returning those options to the agent’s dashboard configuration.

window.chatbase.resetOptions(); // clear every override
window.chatbase.resetOptions({ displayName: true, footer: true }); // clear specific keys

Parameters

object

An object mapping option keys to true for each override to clear. When omitted, every runtime override is cleared.

Per-field methods

Each option also has a dedicated setter that behaves exactly like setOptions with that single key:

window.chatbase.setDisplayName("Acme Support");
window.chatbase.setFooterText("Powered by Acme");
window.chatbase.setMessagePlaceholder("Ask us anything…");
window.chatbase.setDismissibleNotice("Chats may be recorded.");
window.chatbase.setSuggestedMessages(["Track my order", "Talk to a human"]);
window.chatbase.setInitialMessages(["Hi!"]); // legacy alias — see Custom Initial Messages

Examples

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

Custom Buttons

Trigger chat bubble 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 chat bubble 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 chat bubble
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

Chat bubble Control

Methods

open(options?)

close()

resetChat()

Runtime Options

setOptions(options)

resetOptions(fields?)

Per-field methods

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

​Runtime Options

​setOptions(options)

​resetOptions(fields?)

​Per-field methods

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

Runtime Options

setOptions(options)

resetOptions(fields?)

Per-field methods

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