API References

The ChatWidget component is the main entry point to add chat functionality to your site.

ChatWidget Props

Below is the list of props accepted by the ChatWidget component. All are optional except if you want real API connectivity (require apiUrl).

Prop	Type	Default	Description
apiUrl	string | undefined	-	Base URL of your chat API. When provided (without a custom `streamResponse`), the widget will automatically use `useSSEStream` to connect to `<apiUrl>/v1/chat` with an OpenAI-compatible payload. @example "https://your-api.railway.app"
apiToken	string | undefined	-	Bearer token for API authentication. Never commit this - pass via environment variable. @example process.env.CHAT_API_TOKEN
position	ChatPosition | undefined	bottom-right	Position of the floating button and chat panel.
theme	ChatTheme | undefined	dark	Color theme preset.
colors	ChatColors | undefined	-	Custom color overrides - merged with theme defaults.
title	string | undefined	Ask AI	Title shown in the chat panel header.
placeholder	string | undefined	Ask me anything...	Placeholder text in the message input.
initialMessage	string | undefined	Hello! How can I help you today?	First message displayed when the panel opens.
defaultOpen	boolean | undefined	false	Whether the chat panel starts open.
labels	ChatLabels | undefined	-	Custom text labels for technical indicators in the UI.
persistenceKey	string | undefined	ask_widget_session	The localStorage key used to persist chat history.
streamResponse	ChatStreamHandler | undefined	-	Custom response handler - takes full control of streaming. Use this when you need custom fetch logic, auth flows, or a non-SSE backend. When provided, `apiUrl` and `apiToken` are ignored. @example ```ts const streamResponse: ChatStreamHandler = async function* (message, history) { const res = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ message }) }) const reader = res.body!.getReader() // ... yield decoded tokens } ```

ChatStreamHandler Type

If you have a non-standard API or require custom fetch logic, you can pass a streamResponse handler:

export type ChatStreamResult =
  | string
  | AsyncIterable<string>
  | Promise<string | AsyncIterable<string>>;

export type ChatStreamHandler = (message: string, history: ChatMessage[]) => ChatStreamResult;

Example Usage

const streamResponse: ChatStreamHandler = async function* (message, history) {
  const res = await fetch('/api/chat', {
    method: 'POST',
    body: JSON.stringify({ message, history })
  })

  if (!res.ok) throw new Error('API request failed')

  const reader = res.body!.getReader()
  // decode and yield tokens...
}

<ChatWidget streamResponse={streamResponse} />