WidgetConfig.experienceId
Core configuration
Complete reference for all configuration options available in the Nexus Chat Widget. Use the search to find specific options, or browse the tree structure below.
experienceIdstringCore configuration
apiUrlstringaccessTokenstringoptionalOptional access token for authentication
theme"light" | "dark"optionalGlobal theme
typographyobjectoptionalGlobal typography settings These provide base values that can be overridden by component-specific settings
embeddedbooleanoptionalWhether the widget is embedded in the page (default: false)
useShadowDOMbooleanoptionalEnable Shadow DOM for complete CSS isolation. When true, the widget renders inside a Shadow DOM boundary, providing: - Complete bidirectional CSS isolation - No selector conflicts with host page - Protection from hostile CSS overrides Trade-offs: - Some third-party tools may not work (analytics that query DOM) - Inherited CSS properties (color, font-family) still cascade in
falsedisableTabSyncbooleanoptionalDisable cross-tab synchronization. When false (the default), the widget synchronizes session, messages, and state across multiple browser tabs using BroadcastChannel API with localStorage fallback. Set to true when: - Different pages serve different purposes (multi-context applications) - Testing widget behavior in isolation - Users may have different accounts open in different tabs - Privacy requirements prevent state sharing between tabs
falsewindowobjectoptionalChat window/viewport configuration
bubblesobjectoptionalMessage bubbles configuration
inputInputConfigoptionalInput area configuration
messagesobjectoptionalMessages/content
disclaimerobjectoptionalDisclaimer configuration
brandingobjectoptionalBranding configuration
featuresobjectoptionalFeatures configuration
eventsobjectoptionalEvent rendering configuration
scrollbarScrollbarConfigoptionalScrollbar styling configuration for the message container. Allows customization of scrollbar appearance (width, colors, border-radius) and auto-hide behavior. When not provided, browser default scrollbar is used.
scrollbar: {
width: "8px",
thumbColor: "#888",
trackColor: "#f1f1f1",
autoHide: true
}advancedobjectoptionalAdvanced settings
For detailed explanations and examples, see the Configuration Guide.
Core configuration
Optional access token for authentication
Global theme
Global typography settings These provide base values that can be overridden by component-specific settings
Base font size for the entire widget This sets the root font size from which all relative sizes are calculated
Default: "base" (16px)
"base" (16px)"14px""1rem"Whether the widget is embedded in the page (default: false)
Enable Shadow DOM for complete CSS isolation. When true, the widget renders inside a Shadow DOM boundary, providing: - Complete bidirectional CSS isolation - No selector conflicts with host page - Protection from hostile CSS overrides Trade-offs: - Some third-party tools may not work (analytics that query DOM) - Inherited CSS properties (color, font-family) still cascade in
Default: false
Disable cross-tab synchronization. When false (the default), the widget synchronizes session, messages, and state across multiple browser tabs using BroadcastChannel API with localStorage fallback. Set to true when: - Different pages serve different purposes (multi-context applications) - Testing widget behavior in isolation - Users may have different accounts open in different tabs - Privacy requirements prevent state sharing between tabs
Default: false
Chat button configuration
Custom icon
Chat window/viewport configuration
Top accent bar
Height of top accent bar (default: "4px")
Window sizing options
Allow user to resize the window
Default mode name
Show the size toggle button
Remember user's size preference
Disable automatic mobile mode switching (default: false)
Header specific
Font family for header text
Font size for header title text
Default: undefined (inherits base font size)
"lg""18px"Color for header icons (close, menu, size toggle)
Show size toggle in header
Header padding (default: "12px")
Header bottom border shorthand Set to "none" to remove border entirely
"1px solid #e5e7eb""none"Header bottom border color
"#e5e7eb""transparent"Header bottom border width
Default: "1px"
"2px""0"Message bubbles configuration
For messages with avatars, this width is adjusted using calc() to account for avatar space
Default avatar styling for all message bubbles Can be overridden by role-specific avatar configs
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"User messages
Background color on hover (optional, defaults to brightness filter)
Enable/disable hover effect (default: true)
Font family for user message text
Font size for user message text
Default: undefined (inherits base font size)
"base""15px"Full border shorthand (e.g., "1px solid #ccc")
Border width (e.g., "1px", "2px")
Border color
Border style (e.g., "solid", "dashed", "dotted")
Padding inside message bubble (CSS shorthand, default: "8px 16px")
Assistant messages
Background color on hover (optional, defaults to brightness filter)
Enable/disable hover effect (default: true)
Font family for assistant message text
Font size for assistant message text
Default: undefined (inherits base font size)
"base""15px"Full border shorthand (e.g., "1px solid #ccc")
Border width (e.g., "1px", "2px")
Border color
Border style (e.g., "solid", "dashed", "dotted")
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"Padding inside message bubble (CSS shorthand, default: "8px 16px")
Live agent messages
Background color on hover (optional, defaults to brightness filter)
Enable/disable hover effect (default: true)
Font family for agent message text
Font size for agent message text
Default: undefined (inherits base font size)
"base""15px"Full border shorthand (e.g., "1px solid #ccc")
Border width (e.g., "1px", "2px")
Border color
Border style (e.g., "solid", "dashed", "dotted")
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"Show a badge indicating live agent
Custom text for the badge (default: "Live Agent")
Badge background color
Padding inside message bubble (CSS shorthand, default: "8px 16px")
Shared bubble settings
Input area configuration
Placeholder text for input field
Color for placeholder text (default: browser default)
Font style for placeholder ("normal" | "italic" | "oblique")
Background color for input area
Text color for input field
Full border shorthand (e.g., "2px solid #D5D6D9") Takes precedence over individual border properties when set
"1px solid #ccc""2px solid #D5D6D9""none"Border color for input area
Border radius for input area
Border width (default: "1px")
Font family for input text (default: system fonts)
Font size for input text
Default: undefined (inherits base font size)
"base""14px"Send button configuration Groups all send button styling properties
Base color for the send button (used for background in filled mode, text in text mode)
"#3B82F6"Custom text label for the send button (replaces default icon)
"Send"Font family for send button text
"Arial, sans-serif"Font size for send button text
"base""14px"Font weight for send button text
"semibold"Padding inside the send button
"8px 16px"Button appearance mode - "filled": Solid background with contrasting text (default) - "text": Transparent background with colored text
Default: "filled"
Background color (overrides color for filled mode, allows transparent)
"#3B82F6""transparent"Border for send button
"1px solid #ccc""none"Border radius for send button Falls back to input.borderRadius if not specified
"8px""50%"Text/icon color for send button
"#ffffff"Opacity when button is disabled
Default: "0.5"
Text/icon color when button is disabled
"rgba(0, 0, 0, 0.3)"Color for microphone button (not yet implemented)
Font size for send button text (when sendButtonText is set)
"base""14px""1.5rem"Font weight for send button text (when sendButtonText is set)
"bold""semibold"Maximum number of rows for auto-expanding textarea (default: 2)
Maximum height as CSS value (e.g., "120px", "10vh") - takes precedence over maxRows
Minimum number of rows for textarea (default: 1)
Padding inside textarea (default: "8px 12px")
Gap between textarea and buttons (default: "8px")
Whether button appears inside input border (default: false)
Configuration for the border above the input area. - Set to `false` to hide the border - Set to `true` or omit to show the default border (maintains current behavior) - Set to object for full customization
Default: true
Whether to show the border
Default: true
Custom border color (CSS color value)
Default: Theme-based gray (#e5e7eb in light mode, #374151 in dark mode)
Border width (CSS width value)
Default: "1px"
Whether to autofocus the input field when the widget first loads.
Default: false
Whether to autofocus the input field after receiving a bot response. Useful to disable on demo pages with multiple widgets to prevent focus conflicts.
Default: true
Messages/content
Display mode for welcome message (default: "static")
Show avatar on welcome message bubble (default: true, only applies when welcomeMessageDisplay is "bubble")
Whether welcome message persists through conversation (default: false)
Actions for welcome message (only displayed in bubble mode)
Only bottom supported in Phase 1
Horizontal alignment
Gap between buttons (CSS value)
Array of actions
Unique identifier for this action
Display text
Optional icon
SVG string, URL, or emoji character
Action to perform
Visual styling
Action button border (shorthand)
"2px solid #e5e7eb"Action button border width (granular)
"2px"Action button border color (granular)
"#10b981"Action button border style (granular)
"solid", "dashed", "dotted"Behavior flags
Disable after first click
Disable all buttons in group when this one is clicked (requires oneTimeUse)
Auto-disable after N more turns
Manually disabled
Why disabled (for tooltip)
Post-click confirmation
Remove all action buttons after this action is clicked
Confirmation message to display after action click
Format of the confirmation message (default: "markdown")
Alignment of confirmation message (default: "center")
Text color for confirmation message (CSS color value)
Icon to display with confirmation message
SVG string, URL, or emoji character
Whether to show the icon (default: true if confirmationIcon provided)
Show a system event in the chat history (default: false)
Custom message for the system event (defaults to action-specific message)
Type of system event to show (default: "info")
Display options
Show text label
Show icon
Show tooltip on hover
Custom tooltip text
Message shown when session has expired due to inactivity
Default: "This conversation has ended due to inactivity. Please start a new conversation."
Style of loading animation
Color for loading animation
Link styling configuration Applies to all links in markdown content across all message types
Link text color (CSS color value)
"#0066cc""rgb(0, 102, 204)"Link hover state color (CSS color value) Defaults to the same color as `color` if not specified
"#0052a3"Whether to underline links
Default: true
Whether links should open in a new tab
Default: true
Font weight for link text Uses named presets that map to standard CSS font-weight values
Default: undefined (inherits from parent styles)
"bold""normal"Font size for link text Uses named presets or custom CSS values
Default: undefined (inherits base font size)
"sm""16px""1.25rem"Markdown rendering configuration
Apply semantic typography sizes to markdown elements (headings, code) When true: h1 uses xl, h2 uses lg, h3 uses base, h4-h6 use sm, code uses sm When false: all elements inherit the bubble's fontSize configuration
Default: false
Whether to automatically scroll to the bottom when new messages are added. Useful to disable on demo pages with multiple widgets to prevent unexpected scrolling.
Default: true
Disclaimer configuration
Markdown content for disclaimer
Format of disclaimer content
Display mode for the disclaimer. - "footer": Fixed at bottom of widget (default, current behavior) - "modal": Blocking overlay requiring acceptance (when required: true) - "event": Scrollable event at top of message stream
Default: "footer"
Footer mode options (existing)
Whether to start expanded (default: false)
Background color for disclaimer section
Text color for disclaimer
Border color
Show accept/acknowledge button
Custom text for accept button
When true, displays a blocking modal that requires acceptance before interaction. Acceptance is persisted per-experience in localStorage.
Default: false
Title displayed at the top of the blocking modal. Only applies when required is true.
Default: "Disclaimer"
Text for the accept button in the blocking modal. Only applies when required is true.
Default: "I Accept"
When displayMode is "event" and this is true, input is disabled until the disclaimer is accepted. Similar to required modal but inline.
Default: false
Branding configuration
Features configuration
Whether voice input feature is available (default: false)
Language code (e.g., 'en-US', 'es-ES')
Keep listening until stopped
Show results as user speaks
Number of alternative transcriptions
Whether TTS feature is available
Whether TTS is on by default
Required to enable the copy button
Position relative to message (default: "inline")
Whether to show "Copy" text (default: true)
Whether to show icon (default: true)
Button style (default: "default")
Button size (default: "small")
Custom styling
Custom icon color
Custom text color
Custom background color
Custom hover background
Custom icons (SVG strings or URLs)
Custom success icon
Behavior
Custom tooltip text (default: "Copy message")
Custom success text (default: "Copied")
Whether feedback feature is enabled
Position of feedback buttons relative to message
Style of feedback buttons
Whether to show feedback on assistant messages (default: true)
Whether to show feedback on agent messages (default: true)
Whether to require a comment with negative feedback
Custom prompt text for feedback comment
Visual customization
Button size
Spacing between buttons (CSS value)
Whether to show text labels with icons
Animation when hovering/clicking
Colors for different states
Custom icon HTML/SVG or emoji (default: thumbs up)
Custom label text (default: "Helpful")
Icon/text color when not selected
Color when selected
Color on hover
Background color when not selected
Background when selected
Custom icon HTML/SVG or emoji (default: thumbs down)
Custom label text (default: "Not helpful")
Icon/text color when not selected
Color when selected
Color on hover
Background color when not selected
Background when selected
For star rating style
Color of unselected stars
Color of selected stars
For emoji style
Behavior customization
Allow users to change their feedback (default: true)
Show confirmation message after feedback (default: true)
Custom confirmation message
How long to show confirmation (ms)
Remember feedback across sessions (default: false)
API customization
Custom endpoint for feedback (defaults to /feedback)
Include conversation context with feedback
Additional data to send with feedback
Clear Conversation menu option configuration
Whether to show the "Clear Conversation" menu option
Default: true
Custom label text for the menu option
Default: "Clear Conversation"
Event rendering configuration
Default styling configuration for all events Can be overridden by individual event type configurations
Font size for event text (preset or custom CSS value)
Font family for event text
Font style for event text (normal, italic, oblique)
Text color for event content
Background color for event container
Border radius for event container
Padding inside event container (CSS shorthand)
Default avatar styling for all events
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"Font size for event text (preset or custom CSS value)
Font family for event text
Font style for event text (normal, italic, oblique)
Text color for event content
Background color for event container
Border radius for event container
Padding inside event container (CSS shorthand)
Default avatar styling for all events
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"Whether to show session start events (default: true)
Whether to show the badge/pill indicator (default: true)
Whether to show the timestamp (default: false)
Layout mode (default: "vertical")
Custom message to display
Format of the message (default: "text")
Custom badge background color
Custom badge text color
Custom badge text (default: "Session Started")
Custom icon color
Font size for event text (preset or custom CSS value)
Font family for event text
Font style for event text (normal, italic, oblique)
Text color for event content
Background color for event container
Border radius for event container
Padding inside event container (CSS shorthand)
Default avatar styling for all events
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"Whether to show session end events (default: true)
Whether to show the badge/pill indicator (default: true)
Whether to show the timestamp (default: false)
Whether to show session duration (default: true)
Layout mode (default: "vertical")
Custom message to display
Format of the message (default: "text")
Custom badge background color
Custom badge text color
Custom icon color
Font size for event text (preset or custom CSS value)
Font family for event text
Font style for event text (normal, italic, oblique)
Text color for event content
Background color for event container
Border radius for event container
Padding inside event container (CSS shorthand)
Avatar styling for agent handover events Overrides events.default.avatar if specified
Whether to show the avatar
Default: true
Avatar image URL If not provided, falls back to default avatar icon
"https://api.dicebear.com/7.x/avataaars/svg?seed=agent"Avatar size Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px) Or provide custom CSS value: "40px", "2.5rem", etc.
Avatar border radius Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px) Or provide custom CSS value: "50%", "12px", etc.
Avatar border (shorthand)
"2px solid #e5e7eb"Avatar border width (granular)
"2px"Avatar border color (granular)
"#10b981"Avatar border style (granular)
"solid", "dashed", "dotted"Avatar margin (spacing around avatar)
Default: "0 12px 0 0" (message bubbles)
"0 12px 0 0"Whether to show agent handover events (default: true)
Whether to show the card layout (default: true)
Whether to show the timestamp (default: false)
Layout mode (default: "vertical")
Custom message to display (overrides event message)
Format of the message (default: "text")
Custom card background color
Custom card border color
Custom card text color
Whether to show typing indicators (default: true)
Custom typing text (default: "{role} is typing")
Whether to show system messages (default: true)
Whether to show icons (default: true)
Whether to show disclaimer events (default: true)
Whether to show icon (default: true)
Custom icon color
Custom background color (use "transparent" or "none" to remove)
Custom text color
Custom border color (use "transparent" or "none" to remove)
Custom border radius
Custom padding
Custom font size
Accept button styling
Custom accept button text color
Custom accept button border radius
Custom accept button padding
Custom accept button font size
Acknowledged indicator styling
Custom text for acknowledged indicator (default: "Acknowledged")
Custom color for acknowledged text
Scrollbar styling configuration for the message container. Allows customization of scrollbar appearance (width, colors, border-radius) and auto-hide behavior. When not provided, browser default scrollbar is used.
scrollbar: {
width: "8px",
thumbColor: "#888",
trackColor: "#f1f1f1",
autoHide: true
}Width of the scrollbar. Can be a pixel value (e.g., "8px") or "thin". Maps to custom scrollbar size across all browsers.
Default: Browser default
Background color of the scrollbar track. Works consistently across all browsers.
Default: Browser default
Color of the scrollbar thumb. Works consistently across all browsers.
Default: Browser default
Color of the scrollbar thumb on hover. Works consistently across all browsers.
Default: thumbColor or browser default
Border radius of the scrollbar thumb and track. Works consistently across all browsers.
Default: Browser default
Enable auto-hide scrollbar behavior. When enabled, scrollbar automatically hides after a period of inactivity and reappears on scroll or hover. Works consistently across all browsers via JavaScript implementation.
Default: false
Delay in milliseconds before auto-hiding the scrollbar. Only applies when autoHide is enabled.
Default: 1000
Advanced settings
Optional user identifier to associate with the session. Accepts flexible formats: UUID, email address, numeric ID, or custom string (max 255 characters). Normalized to lowercase for storage and comparison.
"userOptional session ID to initialize the widget with an existing session. Must be a valid UUID v4 format. Use this to resume a session across page reloads or coordinate multiple widgets.
"550e8400-e29b-41d4-a716-446655440000"Custom HTTP headers to include in all API requests. These headers are passed through to the backend API endpoints (query, feedback, TTS synthesis). Built-in headers (Content-Type, Authorization) cannot be overridden. If you provide headers with these names, the built-in values will take precedence. Use cases: - Passing correlation IDs for distributed tracing - Including custom authentication tokens for proxy infrastructure - Adding customer-specific identifiers
headers: {
"X-Correlation-ID": "abc-123",
"X-Customer-ID": "customer-456"
}Credentials mode for fetch API requests. Controls whether cookies and HTTP authentication are sent with cross-origin requests. - "omit": Never send credentials - "same-origin": Only send credentials for same-origin requests (browser default) - "include": Always send credentials, including cross-origin When using "include", the server must respond with: - `Access-Control-Allow-Credentials: true` - `Access-Control-Allow-Origin` set to a specific origin (not `*`)
Default: undefined (browser default: "same-origin")
advanced: {
credentials: "include", // Send cookies with cross-origin requests
}Configuration for the readonly mode indicator badge. Used both for initial config and runtime updates via setReadOnly().
Whether to show the indicator badge. Default: false
Text to display in the indicator. Default: "Unavailable"
Background color of the indicator badge
Text color of the indicator badge
Whether to persist the store across widget instances. When true (the default), the store is managed as a singleton by the ChatStoreManager, meaning multiple widget instances with the same experienceId share state and conversation history persists across page navigations. When false, a new isolated store is created for each widget instance. The store is not shared and is reset when the widget is destroyed. Set to false when: - Running tests that need isolated widget state - Multiple independent widgets on the same page need separate conversations - Privacy requirements prevent any state persistence - Building demo/preview widgets where state should not persist Note: When persistStore is false, the disableTabSync option has no effect because isolated stores do not use the tab synchronization infrastructure.
Default: true (undefined is treated as true)
Custom key for the persistent store. When using persistent stores, this key identifies the store instance. Useful when you need multiple distinct persistent stores.
Default: experienceId
Maximum number of chat events to store in localStorage for cross-tab synchronization and session persistence. Older events are automatically pruned when this limit is exceeded.
Default: 500
Message interceptor function for custom routing Called before each message is sent to Nexus backend
Timeout for message interceptor in milliseconds
Default: 30000 (30 seconds)
Timeout for all message operations (including backend requests) in milliseconds
Default: 60000 (60 seconds)
Custom handlers for links with custom protocols in AI responses. ## Supported Protocols Any protocol not in the standard list (http:, https:, mailto:, tel:) is treated as a custom protocol and will: 1. Have navigation prevented (won't open about:blank) 2. Emit a `linkClick` event with parsed protocol and params 3. Invoke the matching handler if registered ## Markdown Syntax AI responses can include action links: ```markdown [Speak to an Agent](action:escalate-to-agent) [Contact Support](livechat:department=billing&priority=high) [Show tutorial](walkme:flowId=12345) ``` ## Parameter Parsing - Key-value: `protocol:key=value&key2=value2` -> `{ key: "value", key2: "value2" }` - Simple value: `protocol:value` -> `{ value: "value" }`
advanced: {
customProtocolHandlers: {
// Live agent escalation
"action:": (params, event) => {
if (params.value === "escalate-to-agent") {
myLiveAgentSDK.escalate({
sessionId: event.sessionId,
context: "user-requested"
});
}
},
// Parameterized live chat
"livechat:": (params, event) => {
myLiveAgentSDK.open({
department: params.department,
priority: params.priority || "normal"
});
},
// WalkMe integration
"walkme:": (params) => {
if (window.WalkMeAPI && params.flowId) {
window.WalkMeAPI.startFlowById(parseInt(params.flowId));
}
}
}
}Analytics configuration for tracking user interactions.
Track link clicks in AI responses. When enabled, link click events are sent to the backend for analytics. Enabled by default - set to false to disable.
Default: true