@caylex/chat-widget

An embeddable React chat widget powered by a Caylex agent.

Drop a fully-featured chat UI into any React app with two lines of code. The widget handles streaming responses, tool calls, saved sessions, theming, and auth-token refresh.

Installation

npm install @caylex/chat-widget
# or
yarn add @caylex/chat-widget

The widget has the following peer dependencies — install them in your app if you don't already have them:

npm install react react-dom antd @ant-design/cssinjs @emotion/cache @emotion/react @emotion/styled @ant-design/icons lodash.merge react-markdown remark-gfm @caylex/shared

Usage

import { CaylexChatWidget } from '@caylex/chat-widget';

export function MyPage() {
  return (
    <CaylexChatWidget
      apiBaseUrl="https://api.caylex.ai/api/v1/assistants/"
      widgetToken="YOUR_WIDGET_TOKEN"
      userName="John"
      sampleQueries={['What can you do?', 'Help me with...']}
      theme="light"
      primaryColor="#3F58CF"
      backgroundColor="#FFFFFF"
    />
  );
}

Widget tokens

Widget tokens are short-lived JWTs minted by your backend via POST /widget/mint-token. Pass an async refreshToken callback to auto-refresh on 401:

<CaylexChatWidget
  apiBaseUrl="..."
  widgetToken={token}
  refreshToken={async () => {
    const res = await fetch('/api/mint-widget-token', { method: 'POST' });
    const { token } = await res.json();
    return token;
  }}
/>

Configuration

See the CaylexChatWidgetConfig type for all available props (theme colors, session behavior, callbacks, etc.).

Host-managed sessions

Use initialSessionId when the host application owns the mapping between its resources and Caylex sessions. Pass a session ID to restore it, null to explicitly create a new session, or omit the prop to retain the widget's browser-session restoration behavior.

<CaylexChatWidget
  apiBaseUrl="..."
  widgetToken={token}
  initialSessionId={savedSessionId ?? null}
  onSessionCreated={(sessionId) => saveSessionId(sessionId)}
  onSessionChanged={({ sessionId, sessionType }) => {
    console.log('Active Caylex session', sessionId, sessionType);
  }}
/>

onSessionCreated fires only for sessions created by the widget. onSessionChanged fires whenever the active chat or background-task session changes.

Compact voice-first presentation

Use the compact presentation for a small voice-first control that can expand into the full chat without recreating its Caylex session or voice connection:

<CaylexChatWidget
  apiBaseUrl="..."
  widgetToken={token}
  presentation="compact"
  compactWidth={360}
  onExpandedChange={(expanded) => {
    console.log('Widget expanded', expanded);
  }}
/>

The compact view shows recent assistant text, transcription and live-voice controls, and automatically expands when user approval is required. The full widget remains the default when presentation is omitted.

CDN usage

A standalone UMD bundle is also available for plain HTML pages:

<div id="caylex-chat"></div>
<script src="https://cdn.caylex.ai/chat-widget.js"></script>
<script>
  CaylexChat.render('#caylex-chat', {
    apiBaseUrl: 'https://api.caylex.ai/api/v1/assistants/',
    widgetToken: 'YOUR_WIDGET_TOKEN',
  });
</script>

License

Proprietary © Caylex