Chatbot

How to embed and configure the Flourish Agent Platform Chatbot component.

Overview

The Chatbot is a conversational chat interface connected to the Flourish Agent Platform. Add it to any Salesforce page — a record page, an app page, a community — and it connects automatically to the agent you specify.

The Chatbot can also be embedded on external websites outside of Salesforce using an HTML snippet generated from the Agent Builder. See Embedding on External Websites for details.

Out of the box, the Chatbot handles streaming responses, markdown rendering, file attachments, file downloads, dark mode, and automatic reconnection if the connection drops.

Adding the Chatbot to a Salesforce Page

In App Builder, drag the Chatbot component onto your page layout and set the Agent ID property to either a Salesforce Agent record ID or a Flourish Agent ID. The component resolves both automatically.

On record pages, the component automatically picks up the page's record ID and passes it through to the agent as context.

Properties

Property	Default	Description
Agent ID	—	Required. A Salesforce Agent record ID or a Flourish Agent ID.
Record ID	—	Populated automatically on record pages. Used as a fallback if Agent ID is not set.
Height Mode	Medium	Controls the component height: Small (400px), Medium (600px), Large (800px), or Custom.
Custom Height	600px	Used when Height Mode is set to Custom. Accepts any CSS height value (e.g. `600px`, `80vh`).
Hide Footer	Off	Hides the bottom utility bar (Restart, Contact, Report) and the "Powered by Flourish" footer.
Custom Style	—	A JSON string of CSS variable overrides for theming. See Custom Styling.
Context	—	Structured data passed to the agent at runtime. See Passing Context.

Note: Height Mode and Custom Height are available when the component is added programmatically in code. They are not exposed as design properties in App Builder.

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 details, or any other information the agent should be aware of.

Within the agent's Profile or Startup Instructions, reference context values using {{{key}}} template syntax.

See the For Developers section for how to set context programmatically.

Custom Styling

You can override the Chatbot's default colors, border radii, and layout using a JSON string of CSS variable overrides. This lets you brand the chatbot or adjust the look without editing the component source.

Keys use camelCase in the JSON and map to CSS variables automatically.

Themeable Variables

Variable	Description
`bubbleUser`	User message bubble background color
`bubbleBot`	Assistant message bubble background color
`bubbleUserText`	User bubble text color
`bubbleBotText`	Assistant bubble text color
`chatbotContainerRadius`	Outer container border radius
`chatbotHeaderRadius`	Header bar border radius
`messageHistoryMinHeight`	Minimum height for the message area (e.g. `50vh`). Useful in embed mode to prevent the chat from collapsing when there are few messages.

Dark Mode Overrides

You can include a nested "dark" key with separate overrides for dark mode. Light mode values apply by default, and dark mode overrides kick in automatically when the user toggles dark mode.

Example:

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

Dark Mode

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

If your Salesforce environment restricts browser storage, dark mode still works for the session — the preference just won't persist across page loads.

Streaming Responses

The chatbot streams responses in real time. As the agent generates its reply, words appear progressively — no waiting for a full response before anything shows.

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.

Progress Notifications

While the agent is working (between tool calls or reasoning steps), it may send brief progress notifications — short status messages that appear inline in the chat. These are styled as lightweight italic text, distinct from the agent's final response, so you can see what the agent is doing without waiting for the full answer.

Progress notifications appear automatically — no configuration needed.

File Uploads

When Allow File Upload is enabled in the agent's Chat Experience settings, users see a file attachment button (paperclip icon) next to the text input. Files are uploaded to the conversation and become available to the agent for processing via run_code scripts.

How It Works

Click the attachment button and select one or more files (up to 10 per message, 30 MB each).
Selected files appear in the attachment strip above the input — images as thumbnails, other files as compact cards.
Type a message and click Send. The files upload to the server first, then the text message is sent.
While uploading, each file card shows an upload indicator (spinner for files, overlay for images). The indicator clears when the upload completes.
The agent can access uploaded files in its run_code scripts.

If an upload fails (e.g. file too large, network error), the file card shows an error indicator and an error message appears briefly. The text message is still sent even if some uploads fail.

File Downloads

When the agent generates a file (via the File Generation tool and outputs.save() in a run_code script), a download card appears inline in the chat. The card shows the filename, file size, and a Download button.

Clicking Download fetches a fresh download link and opens the file in a new tab. Generated files are retained for 180 days.

Markdown Rendering

Assistant responses are rendered as formatted Markdown, including headings, bold and italic, code blocks, inline code, 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 renderer fails to load, the component falls back to basic inline formatting so the chat remains functional.

Conversation History

When a user returns to the same page (or the same agent in 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, click Restart in the footer utility bar.

Utility Bar

The footer utility bar (visible when Hide Footer is off) 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. A developer can connect them to Salesforce logic such as Case creation.

Connection & Reconnection

The chatbot establishes a live connection to the Agent Platform when it loads. If the connection drops unexpectedly, it automatically retries up to 3 times (waiting 2, 4, and 6 seconds between attempts).

Some errors — such as authentication failures, credential issues, or an agent that can't be loaded — can't be resolved by reconnecting. In those cases, the chatbot shows an inline error message instead of retrying.

Embedding on External Websites

You can embed the chatbot on any website outside of Salesforce — a marketing site, a help center, a client portal, or any page where you can add HTML.

Prerequisites

Before you can generate an embed snippet, two things must be in place:

A Salesforce Site page that hosts the Chatbot component. This is a bare-bones page with nothing but the chatbot — no Salesforce navigation, headers, or chrome. Your Salesforce admin sets this up once, and the URL is stored in the Chatbot_Embed_Site__c field on FL_Intelligence__mdt.
A registered, deployed agent. The embed snippet references the agent's Agent ID, so the agent must be registered on the Agent Platform.

Once both are configured, the Embed button appears in the Agent Builder action bar.

Generating the Snippet

Open the agent in the Agent Builder.
Click Embed in the action bar.
Choose an embed mode:
- Bubble — a floating chat button in the bottom-right corner of the page. Clicking it opens a chat panel. You can customize the button color.
- Inline — an iframe embedded directly in the page flow. It auto-resizes to fit the chatbot's content height.
If using Bubble mode, pick a Button Color using the color picker.
Click Copy to Clipboard.
Paste the snippet into your website's HTML.

Where to Paste the Snippet

Bubble mode: Paste the <script> tag just before the closing </body> tag. It creates the floating button and chat panel automatically — no container element needed.

<body>
  <!-- your page content -->

  <!-- Flourish Chatbot (bubble) -->
  <script>
  (function(){
    // ... snippet content ...
  })();
  </script>
</body>

Inline mode: Paste the snippet wherever you want the chatbot to appear on the page. The <div> wrapper controls the chatbot's position and size.

<div class="my-chat-section">
  <!-- Flourish Chatbot (inline) -->
  <div id="fl-chatbot-wrapper" style="height:600px;width:100%;max-width:480px;">
    <iframe id="fl-chatbot" src="..."
      style="height:100%;width:100%;border:none;border-radius:12px;"
      allow="clipboard-write"></iframe>
  </div>
  <script>
  (function(){
    // ... resize listener ...
  })();
  </script>
</div>

You can adjust the wrapper's max-width, height, and border-radius to fit your page layout.

Bubble Mode Behavior

The bubble embed creates two elements on your page:

A floating button (56px circle) fixed to the bottom-right corner. Clicking it toggles the chat panel open and closed. The button icon switches between a chat icon (closed) and an X (open).
A chat panel (400×600px) that slides in above the button with a subtle animation.

On mobile screens (under 480px wide), the chat panel expands to fill the entire screen for a better experience.

When the agent sends a new message while the panel is closed, the button can be styled to show a notification indicator (the snippet listens for fl__notify events from the chatbot).

Inline Mode Behavior

The inline embed places the chatbot directly in the page flow as an iframe. A small script listens for height-change messages from the chatbot and resizes the wrapper automatically, so the iframe never shows scrollbars or wastes space.

How It Works

The embed snippet loads the chatbot in an iframe pointing to your Salesforce Site page. The agent ID and configuration are passed as URL parameters (c__flagentid, c__flstyle). The chatbot detects that it's running inside an iframe and reads its configuration from the URL instead of from Salesforce component properties.

The iframe communicates with the parent page using postMessage:

Event	Direction	Purpose
`fl__ready`	Chatbot → Parent	The chatbot has loaded and is ready
`fl__resize`	Chatbot → Parent	The chatbot's content height changed (inline mode uses this to resize the wrapper)
`fl__notify`	Chatbot → Parent	The agent finished a response (bubble mode can use this for a notification indicator)

All messages are JSON-encoded and origin-checked for security.

Customizing the Embed

Changing the bubble color: Use the color picker in the Embed modal before copying the snippet, or edit the COLOR variable in the generated script.

Changing the inline size: Edit the style attributes on the wrapper <div> — adjust height, max-width, or border-radius as needed.

Changing the chat panel size (bubble): Edit the CSS in the generated <style> block — look for #fl-chat-panel and adjust width, height, or max-height.

Passing custom styles to the chatbot: Add a c__flstyle URL parameter to the iframe src with a URL-encoded JSON string of CSS variable overrides. For example, to set a minimum message area height: c__flstyle=%7B%22messageHistoryMinHeight%22%3A%2250vh%22%7D.

Reading the agent ID from your page URL: If you want to pass the agent ID dynamically (rather than hardcoding it in the snippet), replace the static src with a script that reads from the page URL and sets c__flagentid programmatically using the URL API.

For Developers

This section covers programmatic usage of the Chatbot component when embedding it as a child Lightning Web Component (LWC) — for example, inside a custom page or another component.

Basic Markup

<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 ID directly to agent-id. The component resolves both automatically.

Property Reference

Property	Type	Default	Description
`agent-id`	`String`	—	Required. Salesforce Agent record ID (15 or 18 chars) or Flourish Agent ID.
`record-id`	`String`	—	Passed automatically on record pages. Fallback if `agent-id` is not set.
`height-mode`	`String`	`medium`	Component height: `small`, `medium`, `large`, or `custom`.
`custom-height`	`String`	`600px`	Used when `height-mode` is `custom`. Any CSS height value.
`hide-footer`	`Boolean`	`false`	Hides the utility bar and "Powered by Flourish" footer.
`custom-style`	`String`	—	JSON string of CSS variable overrides.
`object-api-name`	`String`	—	Auto-populated on record pages. Identifies the host record's object type (e.g. `Account`).
`context`	`Object`	—	Opaque data object passed to the agent at runtime.

Setting Context Programmatically

Pass structured data to the agent from the parent component. When the value changes, the chatbot automatically sends the updated context.

// 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>

Handling Agent Actions

The chatbot dispatches an agentaction custom event when the agent sends a structured action during its response. Actions are delivered via two mechanisms — both produce the same agentaction event on the host side:

Structured delivery (preferred) — agents with Custom Actions configured send actions as typed WebSocket events. The chatbot receives them and dispatches each as an agentaction event.
Text-based delivery (legacy) — agents can embed :::action ... ::: blocks in their response text. The chatbot parses these, strips them from the displayed message, and dispatches them as events.

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>

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

Custom Style Markup

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

CSS Variable Reference

camelCase Key	CSS Variable	Description
`bubbleUser`	`--bubble-user`	User message bubble background
`bubbleBot`	`--bubble-bot`	Assistant message bubble background
`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
`messageHistoryMinHeight`	`--message-history-min-height`	Minimum height for the message area

Embedding Examples

Flush full-height embed (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 (match your org's color scheme):

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

Overview​

Adding the Chatbot to a Salesforce Page​

Properties​

Passing Context​

Custom Styling​

Themeable Variables​

Dark Mode Overrides​

Dark Mode​

Streaming Responses​

Progress Notifications​

File Uploads​

How It Works​

File Downloads​

Markdown Rendering​

Conversation History​

Utility Bar​

Connection & Reconnection​

Embedding on External Websites​

Prerequisites​

Generating the Snippet​

Where to Paste the Snippet​

Bubble Mode Behavior​

Inline Mode Behavior​

How It Works​

Customizing the Embed​

For Developers​

Basic Markup​

Property Reference​

Setting Context Programmatically​

Handling Agent Actions​

Custom Style Markup​

CSS Variable Reference​

Embedding Examples​

Overview

Adding the Chatbot to a Salesforce Page

Properties

Passing Context

Custom Styling

Themeable Variables

Dark Mode Overrides

Dark Mode

Streaming Responses

Progress Notifications

File Uploads

How It Works

File Downloads

Markdown Rendering

Conversation History

Utility Bar

Connection & Reconnection

Embedding on External Websites

Prerequisites

Generating the Snippet

Where to Paste the Snippet

Bubble Mode Behavior

Inline Mode Behavior

How It Works

Customizing the Embed

For Developers

Basic Markup

Property Reference

Setting Context Programmatically

Handling Agent Actions

Custom Style Markup

CSS Variable Reference

Embedding Examples