JavaScript SDK

The npm package is the recommended way to integrate ChattyBox. Import one client into your application, configure its public key and API URL, then mount the maintained interface where your application needs it or use the headless methods with your own components.

Quick Start

bun add @openstaticfish/chattybox

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Call this from your component's cleanup lifecycle when appropriate.
// widget.remove();

Call mountWidget() in browser code from the component or layout where the maintained interface should be available. You can pass { locale: 'fr' } for a route-specific locale.

Get Your Public Configuration

1. Create a project and index your content.
2. Test representative questions in the dashboard.
3. Open Public Keys, create a browser key, and restrict its allowed origins.
4. Open Embed, select that key, and copy the widget API URL shown with the generated snippet.

Public widget API keys are designed to appear in browser code. They identify a project but are not management credentials. Restrict browser keys to the domains that should be allowed to call your chatbot. The package is an ESM client for current Node.js and browser applications that provide fetch.

Mount the Hosted Widget from Code

Use this when you want ChattyBox's maintained interface while controlling where it mounts from application code:

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const widget = chattybox.mountWidget();

// Optional cleanup for a component lifecycle:
widget.remove();

It loads the maintained UI once and is not available during server rendering.

Build Your Own UI

Use the headless methods below when your application owns the message list, input, loading and error states, citations, and accessibility.

Send a Message

import { Chattybox } from '@openstaticfish/chattybox';

const chattybox = new Chattybox({
  apiKey: import.meta.env.PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: import.meta.env.PUBLIC_CHATTYBOX_API_URL,
});

const answer = await chattybox.sendMessage({
  message: 'How do I get started?',
});

console.log(answer.message);
console.log(answer.sources);

Set PUBLIC_CHATTYBOX_API_URL to the exact widget API URL from the Embed tab. The SDK accepts either the deployment root or a URL ending in /chat.

The response contains:

Field	Type	Description
message	string	The generated answer.
conversationId	string	Identifier used to continue this conversation.
sources	string[]	Source URLs retrieved for the answer.

Continue a Conversation

Keep the returned conversation ID in your UI state and send it with the next message:

const followUp = await chattybox.sendMessage({
  message: 'Can you explain the second step?',
  conversationId: answer.conversationId,
});

Do not reuse one conversation ID across unrelated visitors. Create a new conversation by omitting conversationId for their first message.

Handle Errors

import { Chattybox, ChattyboxError } from '@openstaticfish/chattybox';

try {
  await chattybox.sendMessage({ message: 'Where is the API reference?' });
} catch (error) {
  if (error instanceof ChattyboxError) {
    console.error(error.status, error.code, error.message);
  }
}

ChattyboxError.status contains the HTTP status. code is present when the API returns a structured error code.

Reuse Project Settings and Translations

The SDK also exposes getWidgetConfig() and getWidgetTranslations(locale). These methods support clients that want to reproduce the hosted widget's project settings and localized labels:

const [config, labels] = await Promise.all([
  chattybox.getWidgetConfig(),
  chattybox.getWidgetTranslations('en'),
]);

A fully custom UI can ignore them. Keep each visitor's conversationId in that visitor's browser or session state; never share one global conversation ID.

Next Steps

• Prefer a maintained, no-build UI? Install widget.js.
• Customize the hosted UI in Hosted widget customization.
• Before launch, test origin restrictions, fallback answers, citations, and mobile behavior with the launch checklist.