Widget Configuration — ChatbotUI Plugin

Full Configuration Object

OctopusChat.init({
  // ── Required ───────────────────────────────────────────────────────
  serverUrl:        'https://your-octopus-server.com',
  agentId:          'customer-support',

  // ── Display ────────────────────────────────────────────────────────
  mode:             'bubble',        // 'bubble' | 'inline' | 'fullpage'
  position:         'bottom-right',  // 'bottom-right' | 'bottom-left'
  bubbleIcon:       null,            // URL to custom bubble icon SVG/PNG
  headerTitle:      'Support Assistant',
  headerSubtitle:   'Typically replies in seconds',
  placeholderText:  'Type your message...',

  // ── Conversation ───────────────────────────────────────────────────
  initialMessage:   'Hi! How can I help you today?',
  welcomeScreen:    true,            // Show a welcome screen before first message
  persistSession:   true,            // Persist conversation across page reloads (localStorage)

  // ── Actions ────────────────────────────────────────────────────────
  allowedActions:   ['file-upload', 'quick-replies', 'feedback', 'copy'],

  // ── Auth ───────────────────────────────────────────────────────────
  auth: {
    type:  'bearer',                 // 'bearer' | 'apiKey' | 'anonymous'
    token: getUserToken()            // JWT for the current user
  },

  // ── Callbacks ──────────────────────────────────────────────────────
  onMessageSent:        (message) => { },
  onMessageReceived:    (message) => { },
  onConversationStart:  (id) => { },
  onConversationEnd:    (id) => { },
  onError:              (err) => { }
});

Configuration Properties

Property	Type	Default	Description
`serverUrl`	string	— required	Base URL of the Octopus server
`agentId`	string	— required	The agent name or ID to use for conversations
`mode`	string	`bubble`	Display mode: `bubble`, `inline`, or `fullpage`
`position`	string	`bottom-right`	Bubble position: `bottom-right` or `bottom-left`
`initialMessage`	string	null	Opening message the agent sends automatically
`persistSession`	bool	true	Store conversation ID in localStorage for session continuity
`allowedActions`	string[]	['feedback']	Enable specific action buttons in the widget
`auth.type`	string	`anonymous`	Authentication mode for API calls
`auth.token`	string	null	JWT bearer token for the current user

React Component Props

interface ChatWidgetProps {
  serverUrl:        string;
  agentId:          string;
  mode?:            'bubble' | 'inline' | 'fullpage';
  position?:        'bottom-right' | 'bottom-left';
  initialMessage?:  string;
  authToken?:       string;
  theme?:           ChatTheme;
  allowedActions?:  ChatAction[];
  onMessageSent?:   (message: ChatMessage) => void;
  onMessageReceived?: (message: ChatMessage) => void;
  onError?:         (error: Error) => void;
  className?:       string;
  style?:           React.CSSProperties;
}

// Usage with full TypeScript types
<ChatWidget
  serverUrl="https://api.company.com/octopus"
  agentId="hr-assistant"
  authToken={user.accessToken}
  initialMessage="Hello! I can help with HR questions."
  allowedActions={['feedback', 'quick-replies']}
  onMessageSent={(msg) => analytics.track('chat_sent', { length: msg.text.length })}
/>

← Embedding the Widget Next: Streaming Responses →