Chat Interface Control

Use window.$muchat after initializing the chat bubble to connect the widget to your website's buttons, language, theme, and navigation.

MethodsCopy Anchor Link

open()Copy Anchor Link

Open the chat window. This method does not take a message or hidden-message option.

window.$muchat.open();

close() and toggle()Copy Anchor Link

Close the window or switch its state:

window.$muchat.close();
window.$muchat.toggle();
window.$muchat.toggle("open");
window.$muchat.toggle("close");

These methods control the window. To control the launcher bubble separately, use toggleBubbleVisibility().

sendMessage(message)Copy Anchor Link

Send a real user message after muchat:ready. A string opens chat by default:

window.$muchat.sendMessage("Where can I see your pricing?");

To keep the current window state, pass an object:

window.$muchat.sendMessage({
  content: "Where can I see your pricing?",
  openWidget: false
});

Before readiness, after destruction, or before required user identification, the SDK ignores the call. Its return value is not a promise of message delivery. The widget's normal validation and required-form rules still apply.

reset()Copy Anchor Link

Clear the guest session cookie, close the window, and reload a fresh widget session:

window.$muchat.reset();

Runtime OptionsCopy Anchor Link

Appearance, Language, and PositionCopy Anchor Link

window.$muchat.setLocale("en");
window.$muchat.setColorScheme("dark");
window.$muchat.setPosition("right");

Invalid locale, position, or visibility values throw an error. Runtime changes do not save dashboard settings. Use the dashboard for content, colors, avatars, spacing, and initial messages.

Showing and Hiding the BubbleCopy Anchor Link

window.$muchat.toggleBubbleVisibility("hide");
window.$muchat.toggleBubbleVisibility("show");

Hiding the bubble does not close an already open chat window. Provide a clearly labeled custom launcher if visitors still need to open chat. Authenticated-only access still requires successful identification before the bubble can appear.

Configuration Before InitializationCopy Anchor Link

Set window.muchatSettings before calling muchatSDK.run. This example chooses the language, theme, position, and initial bubble visibility:

window.muchatSettings = {
  locale: "en",
  theme: "light",
  position: "right",
  bubble_visible: true
};

Changing this object after initialization does not update the running widget. Use the supported methods above or destroy and initialize it again. MuChat has no public setOptions() or resetOptions() API, and no optionsChanged event confirming a rendered override.

ExamplesCopy Anchor Link

Custom ButtonsCopy Anchor Link

Load this after the buttons exist and the installation script has initialized the SDK:

const helpButton = document.getElementById("help-button");
const closeButton = document.getElementById("close-button");
helpButton?.addEventListener("click", () => window.$muchat.open());
closeButton?.addEventListener("click", () => window.$muchat.close());

Use actual button elements with clear labels. muchat:opened and muchat:closed let you update your own controls when the window changes state.

Answer FAQ QuestionsCopy Anchor Link

Register the readiness listener before the installation code calls muchatSDK.run. Run this after your FAQ buttons exist:

let chatReady = false;
window.addEventListener("muchat:ready", () => {
  chatReady = true;
});

document.querySelectorAll("button[data-question]").forEach((button) => {
  button.addEventListener("click", () => {
    if (!chatReady) return;
    window.$muchat.sendMessage(button.dataset.question);
  });
});

Set each button's data-question to the question it should submit. If authenticated-only access is enabled, user identification must also finish before sending. This example assumes the widget is not subsequently reset or replaced; track that lifecycle in your application's integration.

Contextual HelpCopy Anchor Link

For a visitor browsing pricing, use a visible help button that sends a pricing question when clicked.

Time-Based ResetCopy Anchor Link

The SDK does not expose a reliable user/assistant message event stream for measuring chat inactivity. Do not reset based on a presumed user-message or assistant-message event. If your application owns a timed guest session, it can call reset() when that session expires, after warning the user through its own interface.

Reset After Tool Completion or KeywordsCopy Anchor Link

Browser tool-result and message-content callbacks are not available in the current widget. Do not interpret opening or closing chat as completion of a payment or another protected operation. Confirm the result through your own backend before applying your application's UI changes.

Reset on NavigationCopy Anchor Link

Only reset when a new guest conversation is actually needed. Call this from your router's navigation callback after the widget is ready:

function onEnterNewTask() {
  window.$muchat.reset();
}

A reset does not erase a verified user's identity or conversation. The SDK already reports host-page navigation; reinstalling or resetting the widget on every route is unnecessary.

Widget LifecycleCopy Anchor Link

destroy() and init(options)Copy Anchor Link

destroy() returns a promise that resolves after widget teardown. Await it before initializing again:

await window.$muchat.destroy();
window.$muchat.init({
  websiteToken: "YOUR_WEBSITE_TOKEN",
  baseUrl: "https://widget.mu.chat"
});

Destroy removes the frame, launcher, and SDK-managed listeners. It does not remove your application's window event listeners or the saved session cookie. For account changes and logout, follow Identity Verification.

switchWidget(options, configure?)Copy Anchor Link

Use switchWidget when replacing one widget with another. It awaits destruction and initializes the new instance. The optional callback receives that instance:

await window.$muchat.switchWidget({
  websiteToken: "ANOTHER_WEBSITE_TOKEN",
  baseUrl: "https://widget.mu.chat"
}, (widget) => {
  widget.setLocale("en");
});

Finish one switch before starting another. Resolving this promise means initialization and the optional callback completed; it does not mean the new frame is ready or its user has been verified.

Controlling Without the Embed ScriptCopy Anchor Link

A direct iframe uses a separate protocol. It does not create window.$muchat, and the widget methods above cannot be sent as arbitrary iframe messages. Use the iframe guide for its supported commands, readiness handshake, and origin checks.

Best PracticesCopy Anchor Link

• Initialize once in a shared application layout.
• Wait for readiness for message sending, and identify users before authenticated chat.
• Keep a user's closed chat closed until they request help again.
• Give users time to read a response before replacing or resetting their session.
• Test custom launchers, focus, mobile layout, and account changes on your website.

Next StepsCopy Anchor Link