Configuration Reference

Complete reference for all ChatWidget and PopupChatWidget configuration options.

For setup and authentication, see Quick Start.

Agent Props

Prop	Type	Default	Description
`agentId`	`string`	-	Ensemble agent ID to connect to
`agentVersion`	`AgentVersion`	`'latest'`	Agent version selector

AgentVersion

'latest' - Use the latest version (including drafts)
'published' - Use the latest published version
number - Use a specific version number (e.g., 1, 2)

<ChatWidget
  agentId="agent-abc123"
  agentVersion="published"
  // ...
/>

UI Props

Prop	Type	Default	Description
`title`	`string`	-	Title displayed in the header
`inputPlaceholder`	`string`	`'Type a message...'`	Placeholder text for input field
`displayMode`	`'brief' \| 'full'`	`'brief'`	Message display mode
`className`	`string`	-	Additional CSS class for the container
`styles`	`ChatWidgetStyles`	-	Style customization (see Styling Reference)

Display Modes

'brief' - Collapses previous agent steps, showing only the final response
'full' - Shows all steps and intermediate responses

<ChatWidget
  title="Support Assistant"
  inputPlaceholder="Ask me anything..."
  displayMode="full"
  // ...
/>

Initial Messages

Prop	Type	Description
`initialAssistantMessage`	`string`	Static greeting displayed from the assistant
`initialUserMessage`	`string`	Message sent to the agent immediately on load

These props only apply when there is no existing message history for the thread. If the user has chatted before, these are ignored.

initialAssistantMessage - Displays a static intro message from the assistant (does not invoke the agent)
initialUserMessage - Sends a message to the agent immediately, triggering a response

If both are provided, initialUserMessage takes precedence and initialAssistantMessage is skipped.

// Show a static greeting (no agent call)
<ChatWidget
  initialAssistantMessage="Hi! How can I help you today?"
  // ...
/>

// Auto-start conversation (sends to agent immediately)
<ChatWidget
  initialUserMessage="Show me my account summary"
  // ...
/>

Context

Prop	Type	Description
`dataContext`	`Record<string, unknown>`	Key/value pairs passed to the agent and tools

Context can be passed in two ways:

Secure context - Via JWT token (tamper-proof, server-side)
Client context - Via dataContext prop (for non-sensitive data)

Both are merged, with JWT context taking priority on conflicts.

<ChatWidget
  dataContext={{
    environment: 'production',
    userPreferences: { theme: 'dark' },
  }}
  // ...
/>

Voice Options

Prop	Type	Description
`voice`	`ChatWidgetVoiceOptions`	Text-to-speech configuration

ChatWidgetVoiceOptions

Property	Type	Default	Description
`url`	`string`	-	TTS API endpoint URL
`enabled`	`boolean`	`false`	Enable voice playback
`method`	`string`	`'POST'`	HTTP method
`headers`	`Record<string, string>`	-	Request headers
`payload`	`Record \| (text: string) => Record`	-	Request body or function to generate it
`autoplayLatest`	`boolean`	`false`	Auto-play the latest response

<ChatWidget
  voice={{
    url: 'https://api.example.com/tts',
    enabled: true,
    headers: { Authorization: 'Bearer ...' },
    payload: (text) => ({ text, voice: 'en-US-Neural' }),
    autoplayLatest: true,
  }}
  // ...
/>

Speech-to-Text Options

Prop	Type	Description
`speechToText`	`ChatWidgetSpeechToTextOptions`	Speech recognition configuration

ChatWidgetSpeechToTextOptions

Property	Type	Default	Description
`enabled`	`boolean`	`false`	Enable microphone input
`language`	`string`	`'en-US'`	Recognition language (BCP-47 code)
`silenceTimeout`	`number`	`2000`	Silence duration (ms) before auto-stop
`finalDelay`	`number`	-	Delay before finalizing transcript
`onError`	`(message: string) => void`	-	Error callback

<ChatWidget
  speechToText={{
    enabled: true,
    language: 'en-US',
    silenceTimeout: 3000,
    onError: (msg) => console.error('Speech error:', msg),
  }}
  // ...
/>

Feedback Options

Prop	Type	Description
`feedback`	`ChatWidgetFeedbackOptions`	Message feedback configuration

ChatWidgetFeedbackOptions

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Show thumbs up/down on assistant messages
`requireCommentForNegative`	`boolean`	`false`	Require comment when giving negative feedback

Feedback is submitted to POST {baseUrl}/api/feedback.

<ChatWidget
  feedback={{
    enabled: true,
    requireCommentForNegative: true,
  }}
  // ...
/>

Custom Widgets

Prop	Type	Description
`widgets`	`UIWidgetDefinition[]`	Custom widget renderers

See Custom Widgets for details.

Event Callbacks

Prop	Type	Description
`onError`	`(error: Error) => void`	Called on API errors
`onAuthError`	`() => Promise<string \| null>`	Called on 401; return new token to retry
`onFinish`	`(message: any) => void`	Called when assistant finishes responding
`onData`	`(data: any) => void`	Called on streaming data chunks
`onMessage`	`(message: UIMessage) => void`	Called when a message is added

<ChatWidget
  onError={(err) => console.error('Chat error:', err)}
  onAuthError={async () => {
    const newToken = await refreshToken();
    return newToken;
  }}
  onFinish={(msg) => console.log('Response complete:', msg)}
  // ...
/>

Ref Handle

Access the widget programmatically using a ref:

import { useRef } from 'react';
import { ChatWidget, ChatWidgetHandle } from '@anthropic/client-sdk';

function App() {
  const chatRef = useRef<ChatWidgetHandle>(null);

  const sendGreeting = () => {
    chatRef.current?.sendMessage('Hello!');
  };

  return (
    <>
      <button onClick={sendGreeting}>Send Greeting</button>
      <ChatWidget ref={chatRef} /* ... */ />
    </>
  );
}

ChatWidgetHandle

Method	Type	Description
`sendMessage`	`(message: string) => void`	Send a message programmatically

PopupChatWidget Props

PopupChatWidget accepts all ChatWidget props plus:

Prop	Type	Default	Description
`anchorPosition`	`'end' \| 'start'`	`'end'`	Position of floating button (`end` = right, `start` = left)
`defaultOpen`	`boolean`	`false`	Whether popup is open by default

<PopupChatWidget
  anchorPosition="end"
  defaultOpen={false}
  title="Help"
  // ... all ChatWidget props
/>

Configuration

On this page