Skip to main content
ChattyBox Logo

JavaScript SDK

The JavaScript SDK is the recommended path for new developer-led integrations. Build your own chat experience while ChattyBox operates retrieval, citations, conversations, and scaling. If you want a ready-made UI with no application code, use the fully supported hosted widget instead.

Before You Begin​

  1. Create a project and index your content.
  2. Test representative questions in the dashboard.
  3. Open the project's Embed tab.
  4. Create or select a public widget API key and configure its allowed origins.
  5. Copy the widget API URL shown with the embed 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.

Install​

bun add @openstaticfish/chattybox

The package is an ESM client for current Node.js and browser applications that provide fetch.

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:

FieldTypeDescription
messagestringThe generated answer.
conversationIdstringIdentifier used to continue this conversation.
sourcesstring[]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.

Advanced Widget Compatibility​

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. A fully custom UI can ignore them.

Next Steps​