💬 Chatbot

📖 How to embed and configure the Flourish Intelligence Chatbot component.

Overview

The Chatbot (c-intel_chatbot) is a Lightning Web Component that provides a full conversational chat interface connected to the Flourish Agent Platform. Drop it onto any Salesforce page — a record page, an app page, a community — and it connects automatically to the agent you specify.

The component handles session creation, WebSocket connectivity, streaming responses, markdown rendering, file attachments, dark mode, and reconnection — all out of the box.

Basic Usage

<c-intel_chatbot
    agent-id="a01xx0000001234AAA"
    record-id={recordId}
    height-mode="medium"
    hide-footer={false}>
</c-intel_chatbot>

You can pass either a Salesforce record ID (pointing to an Agent__c record) or a Flourish Agent Platform agent UUID directly to agent-id. The component resolves both automatically.

Properties

Property	Type	Default	Description
`agent-id`	`String`	—	Required. A Salesforce Agent record ID (15 or 18 chars) or a Flourish Agent Platform UUID.
`record-id`	`String`	—	Passed automatically on record pages. Used as a fallback if `agent-id` is not set.
`height-mode`	`String`	`medium`	Controls the component height. See Height Modes.
`custom-height`	`String`	`80%`	Used when `height-mode` is `custom`. Accepts any CSS height value, e.g. `600px`, `80vh`.
`hide-footer`	`Boolean`	`false`	Hides the bottom utility bar (Restart, Contact, Report) and the "Powered by Flourish" footer.
`custom-style`	`String`	—	JSON string of CSS variable overrides for theming. See Custom Styling.
`context`	`Object`	—	An opaque data object passed to the agent at runtime. See Passing Context.

Height Modes

The height-mode property accepts one of four values:

Value	Height
`small`	400px
`medium`	550px
`large`	700px
`custom`	Determined by `custom-height`

For flush embeds (e.g. full-height sidebar panels), set height-mode="custom" and custom-height="100%".

Passing Context

The context property lets the host page pass structured data to the agent at runtime. The agent receives this data as part of every conversation turn — useful for providing record data, user context, or any other information the agent should be aware of.

Context can be set as a JavaScript object from the parent component and updated at any time. When the value changes, the component automatically sends the updated context to the agent over the active WebSocket connection.

// In the parent LWC's JS
get chatbotContext() {
    return {
        recordId: this.recordId,
        accountName: this.account.Name,
        userRole: this.currentUserRole,
    };
}

<c-intel_chatbot
    agent-id="your-agent-uuid"
    context={chatbotContext}>
</c-intel_chatbot>

Within the agent's Profile or Startup Instructions, reference context values using {{{key}}} template syntax — the same syntax as chatbot path variables.

Custom Styling

The custom-style property accepts a JSON string of CSS variable overrides. Use it to brand the chatbot, adjust colors, or change border radii without editing the component's source.

Keys use camelCase and are converted automatically to --kebab-case CSS variables.

<c-intel_chatbot
    agent-id="your-agent-uuid"
    custom-style='{"bubbleUser": "#7C3AED", "chatbotContainerRadius": "0"}'>
</c-intel_chatbot>

Themeable Variables

Variable (camelCase)	CSS Variable	Description
`bubbleUser`	`--bubble-user`	User message bubble background color
`bubbleBot`	`--bubble-bot`	Assistant message bubble background color
`bubbleUserText`	`--bubble-user-text`	User bubble text color
`bubbleBotText`	`--bubble-bot-text`	Assistant bubble text color
`chatbotContainerRadius`	`--chatbot-container-radius`	Outer container border radius
`chatbotHeaderRadius`	`--chatbot-header-radius`	Header bar border radius

Dark Mode Overrides

You can supply a nested "dark" key with separate overrides for dark mode:

{
  "bubbleUser": "#7C3AED",
  "dark": {
    "bubbleUser": "#6D28D9"
  }
}

Light mode values are applied by default. Dark mode overrides are applied automatically when the user toggles dark mode, and restored to light values when they toggle back.

Dark Mode

The chatbot has a built-in dark mode toggle in the header (a sun/moon icon). The user's preference is persisted in localStorage and restored on next load.

If your Salesforce environment restricts localStorage, dark mode will still work for the session — the preference just won't persist across page loads.

Streaming Responses

The chatbot connects to the agent over a WebSocket and streams responses in real time. As the agent types, tokens appear progressively in the chat bubble — no waiting for a full response before anything appears.

The header subtitle shows the agent's live status during a turn:

Status	Meaning
🟢 Online	Connected and idle
Connecting…	Session is being established
Thinking (step N)…	Agent is reasoning through a multi-step problem
Using tool: X	Agent is executing a tool call
Tool complete / failed	Tool call finished

A Stop button replaces the Send button while a response is being generated. Clicking it immediately cancels the response.

File Attachments

Users can attach files to their messages. The attachment strip appears above the input bar when files are pending. Up to 10 files can be attached to a single message.

Supported File Types

Category	Formats
Images	`jpg`, `png`, `gif`, `webp`
Documents	`pdf`, `csv`, `xls`, `xlsx`

Attached images are shown as thumbnails in the strip. Files are shown as a compact card with a file type icon and name.

Markdown Rendering

Assistant responses are rendered as formatted Markdown. The component uses marked.js and DOMPurify (loaded from static resources) for safe, full-featured rendering.

Supported Markdown features include headings, bold and italic, code blocks, inline code, ordered and unordered lists, tables, blockquotes, and links. Links always open in a new tab.

A copy button appears on hover over any assistant message, letting users copy the raw markdown to their clipboard.

If the markdown libraries fail to load, the component falls back to basic inline formatting (bold, italic, code, links) so the chat remains functional.

Conversation History

When a user returns to the same page (or the same agent on the same session), the chatbot can resume a previous conversation by replaying the message history. This happens transparently — no user action required.

To force a brand-new conversation, the user can click Restart in the footer utility bar.

Utility Bar

The footer utility bar (visible when hide-footer is false) provides three actions:

Button	Action
Restart	Clears the chat and starts a fresh conversation
Contact	Opens a contact form for the user to submit their name, email, and a message
Report	Opens an issue report form with a description field and optional email

The Contact and Report forms are starter templates. Submission handlers are stubs (handleClickSubmitContact, handleClickSubmitReportIssue) ready for you to wire to Salesforce logic such as Case creation.

Events

The chatbot dispatches a single custom event: agentaction.

`agentaction`

Fired when the agent emits a structured action block in its response. Action blocks are used by the co-build agent in the Agent Builder, but they can also be used in any host page to let the agent drive UI changes or trigger Salesforce actions.

// In the parent LWC
handleChatEvents(event) {
    const action = event.detail;
    console.log(action.type, action);

    if (action.type === 'navigate_record') {
        this[NavigationMixin.Navigate]({
            type: 'standard__recordPage',
            attributes: { recordId: action.record_id, actionName: 'view' },
        });
    }
}

<c-intel_chatbot
    agent-id="your-agent-uuid"
    onagentaction={handleChatEvents}>
</c-intel_chatbot>

The agent emits action blocks using a structured format in its response:

:::action
{"type": "navigate_record", "record_id": "0013X00000AbCdEF"}
:::

Action blocks are parsed and stripped before the response text is displayed — users never see raw action syntax.

Connection & Reconnection

The chatbot establishes a WebSocket connection during initialization. If the connection drops unexpectedly, it will automatically attempt to reconnect up to 3 times with exponential backoff (2s, 4s, 8s).

Specific close codes indicate authentication or configuration issues that cannot be resolved by reconnecting:

Close Code	Meaning
`4001`	Authentication failed — missing or invalid token
`4002`	Credential resolution error
`4003`	Token does not match the conversation
`4004`	Agent could not be loaded

These errors are shown as inline messages in the chat area rather than triggering reconnect attempts.

Embedding Examples

On a Record Page (App Builder)

Add the component to a record page in App Builder and set agent-id to a Salesforce Agent record ID. The component will automatically receive the page's recordId and pass it through to the agent as context.

Flush Full-Height Embed

Remove the card styling and fill a sidebar panel:

<c-intel_chatbot
    agent-id="your-agent-uuid"
    height-mode="custom"
    custom-height="100%"
    hide-footer={true}
    custom-style='{"chatbotContainerRadius": "0", "chatbotHeaderRadius": "0"}'>
</c-intel_chatbot>

Branded Embed

Override the color scheme to match your brand:

<c-intel_chatbot
    agent-id="your-agent-uuid"
    custom-style='{
        "bubbleUser": "#0F766E",
        "dark": { "bubbleUser": "#0D9488" }
    }'>
</c-intel_chatbot>

Overview​

Basic Usage​

Properties​

Height Modes​

Passing Context​

Custom Styling​

Themeable Variables​

Dark Mode Overrides​

Dark Mode​

Streaming Responses​

File Attachments​

Supported File Types​

Markdown Rendering​

Conversation History​

Utility Bar​

Events​

agentaction​

Connection & Reconnection​

Embedding Examples​

On a Record Page (App Builder)​

Flush Full-Height Embed​

Branded Embed​