@colossal-sh/chat-client

Framework-agnostic client for the Colossal chat widget. It handles config, transport, streaming, identity, cart state, and conversation state — no UI. Use it standalone to build a fully custom widget, or through @colossal-sh/chat-react, which renders the default UI on top of it.

Install

npm install @colossal-sh/chat-client

Quickstart

import { createChatClient } from "@colossal-sh/chat-client";

const client = createChatClient({
  agentUid: "<agent-uid>",
  adapter: { baseUrl: "https://<your-workspace-host>/api/v1" },
});

client.open();
await client.sendMessage("Where is my order?");

client.on("message", (message) => {
  // render it
});

client.destroy();

The agentUid is the widget agent's uid, shown on the agent's Embed tab in Colossal.

WidgetConfig

| Option | Type | Notes | | --- | --- | --- | | agentUid | string | Required. The widget agent to talk to. | | adapter | BackendAdapter \| { baseUrl, headers?, fetch? } | Required. Pass { baseUrl } for the built-in HTTP adapter, or your own BackendAdapter. | | identity | { token?, fetchToken? } | Verified-customer identity: a JWT, or a callback that fetches one. | | embedOrigin | string | Origin of the embedding page, when it differs from location.origin. | | launcher | { hidden?, position?, offset?, icon? } | position is "bottom-right" or "bottom-left"; icon is "chat", "help", or { customIconUrl }. | | theme | PartialTheme | Merged over defaultTheme. | | logoUrl | string | Logo shown in the widget header. | | zIndex, breakpoint | number | Stacking and mobile-layout breakpoint. | | locale, strings | string, Partial<StringCatalog> | Locale and string overrides. | | onEvent | (e: WidgetEvent) => void | Every widget event, for analytics. |

Client API

ChatClient exposes: open / close / toggle, navigate, sendMessage, submitUserChoice, resumeStream, identify(jwt), logout, setCart / requestCartUpdate, loadConversations / loadConversation, update(partialConfig), on(event, cb), stores.{widget,conversations,config}, and destroy.

Also exported: HttpBackendAdapter, defaultTheme / darkVariantOf / mergeTheme / themeToCssVars, isCart, stripCartContext, AdapterRequestError, and the corresponding types (WidgetConfig, Theme, BackendAdapter, WidgetMessage, Cart, UserChoice, …).

Documentation

• Widget agents
• Custom components

License

MIT