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.

For an agent that answers through a page of its own rather than a chat window, see Web Apps.

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

These are what App Builder offers when you drop the component on a page:

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.
Conversation ID	-	Resumes an existing conversation instead of starting a new one.
Group Key	-	Names which memory the agent should use for this conversation: a class, an account, a case. Only applies to agents whose Memory setting is not No memory. A record ID or an account number is usually the right thing to pass.
Custom Style (JSON)	-	A JSON string of styling overrides. See Custom Styling.

Height, the footer, the language and context are not in that panel. They are set in markup by a developer placing the component in code, and the first three also have a home in Custom Style (JSON), which is the way to reach them from App Builder. Height is the layout section, the footer is show, the wording is text. See Custom Styling and Text and language.

The properties available in markup, on top of the five above, are height-mode (small at 400px, medium at 600px, large at 800px, or custom), custom-height (any CSS height, used with height-mode="custom"), hide-footer, language, and context. See For Developers.

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, which is 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 brand, resize, and slim down the Chatbot with a single JSON value (the custom-style property). It has four sections:

colors: palette overrides
show: hide or show individual components
layout: width, height, and shape
text: reword any built-in label

Colors

Key	What it colors
`accent`	The brand color: send button, links, activity spark, focus ring
`accentPress`	Send button hover
`onAccent`	The icon on the send button
`ground`	Background behind the conversation
`surface`	Header bar, composer surface, menus
`surface2`	Table headers, disabled send, subtle fills
`border` / `borderStrong`	Hairlines / the composer's outer border
`textPrimary` / `textMuted` / `textFaint`	Text hierarchy
`userBubble` / `userText`	The user's message bubble
`focusRing`	Glow around the composer when focused

Any color is either a plain string (applies in both themes) or a { "light": …, "dark": … } pair. Dark values switch in automatically with the dark-mode toggle. There is no separate dark section.

Show / Hide Components

Set any of these to false under "show" to hide it: header, avatar, utilityBar, disclaimer, poweredBy.

Layout

Key	Purpose
`width`, `height`, `minHeight`, `maxHeight`	Size of the whole chatbot frame. `"fill"` is shorthand for `100%`.
`bodyHeight`, `bodyMinHeight`, `bodyMaxHeight`	Size of the scrolling message area specifically. `bodyMinHeight` prevents the chat from collapsing when there are few messages.
`radius`, `headerRadius`	Outer container / header corner radius (set to `0` for flush embeds)

"fill" makes the chatbot match its parent, which only works if the parent element actually has a size. Width almost always does; height often doesn't in content-height page regions, where bodyMinHeight is the better tool.

Example:

{
  "colors": {
    "accent": { "light": "#7C3AED", "dark": "#8B5CF6" },
    "userBubble": "#EDE9FE"
  },
  "show": { "poweredBy": false },
  "layout": { "height": "fill", "bodyMinHeight": "50vh" }
}

Text and language

The chatbot's own labels, meaning the composer placeholder, Send, Restart, the file chips and the connection notices, ship translated. Set the language to a locale code like es-us, fr-ca or pt-br and they all switch together.

Use the full code, with the region. A bare language code like es does work, but es-us is the form to store and to pass: it is unambiguous, and it is the only form with somewhere to put a difference on the day Spain and the US need different wording.

You do not always have to set it. The chatbot falls back, in order, to the language property, then the c__fllang URL parameter, which is how an embed passes it in, then the agent's own Interface Language from the Agent Builder's Basics tab, which is en-us unless changed.

Every agent has an interface language, so the practical rule is simple: the agent decides unless the page says otherwise.

A page serving more than one language has to say which one it wants, per placement, through c__fllang or the language property. The chat window will not pick up the page's lang attribute on its own for any agent configured since this setting shipped.

A language that has not been fully translated yet falls back label by label, so you get the translated ones and English for the rest, never a blank button.

Language does not change what the agent says. It translates the chatting interface, not the replies. The reply language is part of the agent's own configuration, so setting the language to Spanish gives you Spanish buttons around an English answer unless the agent is set up to answer in Spanish too.

To reword a label, in any language or regardless of language, use text:

{
  "text": {
    "composerPlaceholder": "Ask about your benefits",
    "restart": { "en": "Start over", "es": "Empezar de nuevo" }
  }
}

A plain string applies in every language. An object picks by language code, matched on the full code first and then on the language. Anything you do not list keeps its built-in wording, and a key that is not one of the ones below is ignored.

The keys are: composerPlaceholder, composerPlaceholderTurn, send, stop, attach, more, moreActions, voiceInput, removeAttachment, attachLimit, copyMessage, jumpToLatest, download, uploading, uploadFailed, typePdf, typeCsv, typeDoc, typeAudio, typeVideo, typeText, typeFile, loading, preview, closePreview, thinking, working, stopping, stoppingHint, agentFallback, getInTouch, voiceStart, voiceStop, toggleDarkMode, restart, contact, report, suggestionsTitle, reconnect, reconnecting, connectionLostOffline, connectionLostFailed, contactInformation, reportAnIssue, contactPrompt, legacyPlaceholder.

attachLimit carries a {0} placeholder for the file count, so you can put the number where your wording wants it.

Right-to-left languages are not available yet. The layout is written left to right throughout, and Arabic text inside it would read worse than English does.

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, with no waiting for a full response before anything shows.

While the agent works, an animated activity spark with a "Thinking…" label appears in the conversation. Internal details such as reasoning steps and tool names are deliberately not shown to end users.

Stopping a reply

A Stop button appears while a response is being generated.

Stopping is not instant, and the button is honest about it. The agent finishes whatever step it is on before it stops, so an ordinary reply stops in a second or two and one running a long piece of code takes as long as that step takes. While it is stopping, the label changes to Stopping… and the button goes inactive: pressing it again achieves nothing.

What Stop always does is drop anything waiting behind the reply. What it cannot always do is stop a sentence already being written. If the agent had started composing its answer, that answer finishes on the Agent Platform even though the chat stops showing it, so the words on screen stop where you stopped them.

Stopping is not a refund. Whatever the agent had already spent is spent.

Nothing is written into the conversation to say a reply was stopped. You asked for it to stop; an explanation arriving afterwards is the thing you were preventing.

Adding to a request while it is working

The box stays open while the agent is working, and the placeholder changes to Add to your request…. Send something and the agent takes it up, usually in the reply it is already writing.

Send appears alongside Stop rather than replacing it, because they are different things to want: Stop abandons the work, Send adds to it.

A message sent this way is inserted above the reply being written, not below it, because one answer covers both questions. If the agent was too far along to take it up, the message runs as the next question instead and gets its own answer.

The box does close for the few seconds after you press Stop. Anything typed then would be thrown away along with everything else in the queue, so it does not accept it in the first place.

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 File Upload is enabled in the Files group on the agent's Tools tab, 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.

Pasting

You can paste into the message box as well as using the paperclip, and it does the sensible thing with whatever is on the clipboard.

A screenshot, or an image, audio, video, document or source file becomes an attachment, exactly as if you had picked it with the paperclip. Any file type works.
A long block of text, over 2000 characters, is attached as pasted-text.txt instead of filling the message box. The box only grows so far, and past that point you cannot read back what you pasted before sending it. Shorter text pastes into the box as normal.
Copying from a spreadsheet or a web page pastes the text, not a picture of it. Those copies put both on the clipboard, and the text is almost always what you meant.

Pasted files are named for you and numbered if you paste several, so three screenshots arrive as three attachments rather than overwriting each other.

Attachments show what kind of file they are, and that is worth reading before you send. The agent can look at images when Image Reading is on, reads text and code directly, and needs the right Python package to open a PDF or a Word document. It has no way to listen to audio or watch video today.

Pasting only attaches when File Upload is enabled for the agent. Without it, pasting behaves the way it always has.

File Downloads

When the agent delivers a file, a card appears inline in the chat.

Images show as a thumbnail with the filename and size, and Preview and Download beneath. Preview opens the picture full size over the conversation: click the thumbnail, or the Preview link. Close it with the X, by clicking outside it, or with Escape. PNG, JPEG, GIF, WebP, BMP, AVIF and SVG all display.

Everything else shows as a download card: an icon, the filename, the 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.

Two things worth knowing:

If an image cannot be shown, usually because the org has not upgraded to a version of the package carrying the storage entries in CSP Trusted Sites, the card quietly becomes an ordinary download card. The file is still there; only the picture is missing.
Delivered files do not reappear when a conversation is reopened. The agent's message about the file comes back, the card does not. Download anything you want to keep before you close the conversation.

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 provides three actions. Hide it with "show": { "utilityBar": false } in Custom Style, or with the hide-footer property in markup.

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 (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.

An error says what to do about it, not only what happened. Two of these read almost identically and want opposite responses, which is why the chatbot adds its own sentence to the platform's:

What went wrong	What the chatbot tells the reader
Too many messages in one conversation, too quickly	Wait a minute or two. It clears on its own.
This agent reached its own monthly spend limit	Retrying cannot help. Raise the limit on the agent or wait for the month to reset. See Cost.
The organization reached its monthly spend limit	Retrying cannot help, and every other agent in the org is refused too until someone raises the org's limit or the month resets.
The agent is not authorized	Configuration rather than something passing.
A reply is already being written	Wait for it to finish.

An agent set to Per person memory refuses a conversation with somebody who has not entered their own access. The error says so, rather than reporting that the agent failed to load. That person needs to fill in the My Access component; see Per person access.

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, with 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.
Optionally enable Test mode (see below) to validate the embed on a live site before launching.
Click Copy to Clipboard and paste the snippet into your website's HTML.

The snippet is a single script tag. All of the widget's logic lives in a centrally hosted script, so fixes and improvements reach your site automatically and you never need to re-paste.

Where to Paste the Snippet

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

<!-- Flourish Chatbot -->
<script src="https://cdn.toflourish.org/agent-platform/v1/chatbot-embed.js" defer
  data-agent-id="YOUR_AGENT_ID"
  data-embed-url="https://yourorg.my.site.com/chatbot"
  data-mode="bubble"
  data-accent="#2A809C"></script>

Inline mode: Paste the snippet wherever you want the chatbot to appear. It builds its own container in place, sized by data-height and data-max-width.

<!-- Flourish Chatbot (inline) -->
<script src="https://cdn.toflourish.org/agent-platform/v1/chatbot-embed.js" defer
  data-agent-id="YOUR_AGENT_ID"
  data-embed-url="https://yourorg.my.site.com/chatbot"
  data-mode="inline"
  data-accent="#2A809C"
  data-height="600"
  data-max-width="480"></script>

Snippet attributes

The Embed modal writes these for you. They are the loader's contract, so the spellings matter.

Attribute	Default	What it does
`data-embed-url`	-	Your Site URL. Required: with nothing to point at, the loader renders nothing at all rather than a broken shell.
`data-agent-id`	-	The agent to open. The loader appends it to your Site URL as `c__flagentid`.
`data-mode`	`bubble`	`bubble` for the floating launcher, `inline` to sit in the page.
`data-accent`	`#2A809C`	Accent color, used for the launcher button.
`data-position`	`right`	`left` or `right`. Bubble mode only.
`data-label`	`Let's chat!`	Text on the launcher button.
`data-title`	`Chat`	Title shown on the panel.
`data-height`	`640`	Height in pixels.
`data-max-width`	none	Width cap in pixels. Leave it off to fill the space.
`data-session`	-	`host` means your own server mints the session and hands it in, instead of the chat window minting one for itself. See Minting the session yourself.
`data-test`	-	Hides the widget from everyone but you. See Test mode.
`data-flstyle`	-	Custom styling JSON, or `off` for the loader's plain defaults.

There is no attribute for the interface language. An embedded chat window takes the agent's own Interface Language, which is the right answer for most sites. To override it for one placement, put the parameter on your Site URL: data-embed-url="https://example.my.site.com/agent/embed?c__fllang=es-us". The loader keeps a query string you have already written and adds its own parameters after it.

Passing the Agent ID

The snippet carries the agent ID in data-agent-id, and the loader appends it to your Site URL as the c__flagentid parameter. You only need to handle this yourself if you're building the iframe by hand or choosing the agent at runtime.

Your own iframe: put the parameter on the Site URL directly.

<iframe src="https://yourorg.my.site.com/chatbot?c__flagentid=YOUR_AGENT_ID"
        allow="clipboard-write"></iframe>

To choose the agent at runtime instead of hardcoding it, see Selecting the Agent at Runtime.

Four things to know:

URL parameters are read only in an iframe. The chatbot checks whether it's embedded before reading them, so a component placed directly on a Lightning page ignores them and uses its design properties instead.
A set property wins over the parameter. The URL value is applied only when the Agent ID property is empty, so leave that property blank on the Site page you use for embedding. Otherwise every embed gets the hardcoded agent no matter what the URL says.
Use the platform Agent ID, the value behind Copy Agent ID in the Agent Builder action bar. A Salesforce record ID also resolves, but it means nothing to an external site.
Treat the ID as public. It's visible in your page source and anyone can change it in the URL, so the agent needs to be shared with whoever will reach it (public access for anonymous website visitors). Don't rely on the ID being unguessable.

The Site URL accepts three parameters in total. Each also works without the c__ prefix (flagentid, flstyle, flparentorigin) if that's easier for your host.

Parameter	Purpose
`c__flagentid`	Which agent to load. Set automatically from `data-agent-id` when you use the loader.
`c__flstyle`	URL-encoded JSON using the Custom Styling contract.
`c__flparentorigin`	Your page's origin, needed for the Host API when your host strips the referrer.

Test Mode

Enable the Test mode toggle in the Embed modal to add data-test="1" to the snippet. With it in place, the chatbot stays completely hidden for normal visitors. It only activates for someone who opens a page with ?testflchatbot=1 in the URL, and it then stays active as they navigate around the site for the rest of their tab session.

This lets you put the snippet on your production website and test it end-to-end before anyone else can see it. To launch for everyone, remove the data-test attribute (or re-copy the snippet with Test mode off).

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 shows a small notification dot (driven by fl__notify events from the chatbot).

Inline Mode Behavior

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

Keeping the Conversation Across Pages

Every link a visitor clicks on your site is a fresh page load, which destroys the chat frame. The loader hands the conversation to the next page so the thread survives, and a bubble panel that was open comes back up without stealing focus.

There is nothing to configure. Two things are worth knowing about where it stops:

It ends with the browser tab, or after 30 idle minutes. That is deliberate. A conversation someone had about their health, their finances, or their employer must not silently reopen for the next person on a shared computer.
It degrades to a fresh conversation, never to an error, if the visitor's browser blocks storage.

FlourishChatbot.reset() ends the thread and starts a new one in place, for a "start over" control of your own.

Customizing the Embed

Changing the bubble color: Use the color picker in the Embed modal before copying, or edit the data-accent attribute on the tag.

Changing the inline size: Adjust data-height and data-max-width on the tag. Both are plain pixel numbers.

Passing custom styles to the chatbot: Put a URL-encoded JSON string on data-flstyle, using the Custom Styling contract, or add a c__flstyle parameter to the data-embed-url value. For example, to keep the message area from collapsing: c__flstyle=%7B%22layout%22%3A%7B%22bodyMinHeight%22%3A%2250vh%22%7D%7D.

Older embeds: Sites embedded with the previous self-contained snippet (a full inline script rather than a one-tag loader) keep working. They just don't receive central updates. Re-copy the new snippet whenever convenient.

Writing code against an embed? The events the iframe exchanges with your page, the methods for driving the conversation from the host, and receiving agent actions are all covered under Iframe Integration.

For Developers

This section covers programmatic usage of the Chatbot: embedding it as a child Lightning Web Component (LWC) inside a custom page or another component, and integrating with it from a page that hosts it in an iframe. Everything involving code, events, or the Host API lives here. See Iframe Integration for the cross-frame equivalents.

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`	Legacy: hides the utility bar. Prefer `show.utilityBar` / `show.poweredBy` in `custom-style`.
`custom-style`	`String`	-	JSON styling contract (`colors` / `show` / `layout` / `text`). See Custom Styling.
`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.
`conversation-id`	`String`	-	Resumes an existing conversation rather than starting a new one.
`group-key`	`String`	-	Names which memory the agent uses for this conversation. Fixed when the conversation starts, so nothing later can name a different one.
`language`	`String`	-	Locale code for the chatbot's own labels, e.g. `es-us`. See Text and language. The property is `language`, not `lang`.

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>

context lands in the agent's host context, which the platform treats as read-only ambient background (used to interpret references like "this record"), not as a data source the agent answers from. To hand the agent data it should actively use, prefer attachData plus sendMessage (below).

Host API Methods

A same-document parent LWC can grab the component via this.template.querySelector (or refs) and call these imperative methods directly. Across an iframe embed, the same three are driven over postMessage. See Driving the Chatbot from the Parent Page.

Method	Signature	Purpose
`sendMessage`	`sendMessage(text, { origin })`	Sends a message. `origin: 'user'` (default) renders a user bubble; `origin: 'host'` delivers a state-change notification (no bubble, and the think loop decides whether to respond). Returns `true` if sent.
`attachData`	`attachData(name, data, contentType?)`	Stages in-memory data (string, JSON-serializable object, or Blob) as a conversation upload the agent reads via `uploads["<name>"]` in `run_code`. Keeps bulk data out of the LLM context window. Returns a `Promise<boolean>`. Requires a live session.
`setHostBusy`	`setHostBusy(isBusy, label?)`	Raises or clears the host's own busy state (locks the composer, shows the indicator with `label`). Independent of the agent's own busy state: it can raise but never clear the agent's.

// In the parent LWC's JS: hand the agent local data, then ask it to use it.
async askOverResults(question, results) {
    const chatbot = this.template.querySelector('c-intel_chatbot');
    chatbot.setHostBusy(true, 'Searching…');
    await chatbot.attachData('results.json', results, 'application/json');
    chatbot.sendMessage(
        `Attached results.json (${results.length} hits). Answer "${question}" from it, citing sources.`,
        { origin: 'host' },
    );
    chatbot.setHostBusy(false);
}

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

The agentaction DOM event reaches a same-document LWC parent. When the chatbot runs in an external iframe, the same action is also posted to the parent window as an fl__action message. Both surfaces fire, from both delivery paths.

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

The custom-style value uses the namespaced contract described in Custom Styling: colors / show / layout, with any value accepting a { "light", "dark" } pair.

<c-intel_chatbot
    agent-id="your-agent-uuid"
    custom-style='{"colors": {"accent": "#7C3AED"}, "layout": {"radius": "0"}}'>
</c-intel_chatbot>

Embedding Examples

Flush full-height embed (fill a sidebar panel):

<c-intel_chatbot
    agent-id="your-agent-uuid"
    custom-style='{
        "show": { "utilityBar": false, "poweredBy": false },
        "layout": { "height": "fill", "radius": "0", "headerRadius": "0" }
    }'>
</c-intel_chatbot>

Branded embed (match your org's color scheme):

<c-intel_chatbot
    agent-id="your-agent-uuid"
    custom-style='{
        "colors": {
            "accent": { "light": "#0F766E", "dark": "#0D9488" },
            "userBubble": { "light": "#CCFBF1", "dark": "#134E4A" }
        }
    }'>
</c-intel_chatbot>

Iframe Integration

When the chatbot runs in an iframe on an external site, your page talks to it over postMessage rather than through component properties and DOM events. The exchange is symmetric with the LWC surface above: the same Host API methods drive the conversation, and the same agent actions come back.

postMessage Events

The hosted script (chatbot-embed.js) reads its configuration from the data-* attributes on its own script tag, then loads the chatbot in an iframe pointing to your Salesforce Site page, passing the agent ID as a URL parameter (c__flagentid). 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's DOM has loaded (fires early, before the chat session exists)
`fl__sessionready`	Chatbot → Parent	The chat session is live, so the Host API (send message / attach data) is now safe to call. Re-fires on reconnect.
`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)
`fl__needsession`	Chatbot → Parent	Only under `data-session="host"`. The chatbot is ready to be handed a session. See Minting the session yourself.
`fl__action`	Chatbot → Parent	The agent invoked a Custom Action. Payload `{ action: 'fl__action', payload: { type, ...params } }`, the cross-frame equivalent of the `agentaction` DOM event.

All messages are JSON-encoded and origin-checked for security. fl__action is posted only to the validated parent origin (never *), since action payloads carry data. If the parent origin can't be determined, the action is not forwarded.

Driving the Chatbot from the Parent Page (Host API)

Beyond receiving events, the parent page can drive an embedded chatbot: send messages, hand the agent data, and show a busy state. This lets the host page act as an orchestrator. For example, run a local search, hand the results to the agent, and have it answer from them.

Because an iframe boundary separates the parent from the chatbot, the parent cannot call the component's methods directly. Instead it posts JSON messages to the iframe; the chatbot validates the sender origin, then invokes the matching method. If you use the hosted chatbot-embed.js loader, a convenience wrapper is exposed as window.FlourishChatbot. If you host your own iframe, post the raw messages yourself.

Parent to chatbot messages:

`action`	Payload	Effect
`fl__sendMessage`	`{ text, origin? }`	Sends a message. `origin: 'host'` (default from the bridge) delivers it as a state-change notification: no user bubble, and the agent's think loop decides whether to respond. `origin: 'user'` injects it as if the user typed it (renders a bubble).
`fl__attachData`	`{ name, data, contentType? }`	Stages in-memory data (string, JSON-serializable object, or Blob) as a conversation upload. The agent reads it via `uploads["<name>"]` in `run_code`, so data never enters the LLM context window until the agent computes over it. Up to 30 MB.
`fl__setHostBusy`	`{ busy, label? }`	Raises or clears the host's busy state (locks the composer, shows the activity indicator with `label`). The host controls only its own flag. It can never clear the agent's own "thinking" state, so it cannot falsely signal "ready for input" mid-response.
`fl__setContext`	`{ context }`	Replaces the ambient values the agent reasons over, such as language, who the visitor is, or what page they are on. Draws no bubble and provokes no reply on its own. It replaces the whole object rather than merging, so send every key you want kept, every time.
`fl__setsession`	`{ session }`	Only under `data-session="host"`. Hands over a session your own server minted. Refused on an ordinary embed, so a page cannot point somebody else's chat at a conversation of its choosing.

fl__attachData followed by fl__sendMessage is safe to fire back-to-back: the chatbot serializes them so the upload completes before the message is sent.

Wait for fl__sessionready if you post raw messages, because anything that arrives before it is dropped. The loader's wrapper below queues instead, so calling it from DOMContentLoaded is safe: it holds up to 25 messages and sends them once the session is live. In bubble mode the frame is not built until the panel first opens, so a queued message waits for that rather than forcing the panel open.

The loader's wrapper. With the hosted chatbot-embed.js in place, window.FlourishChatbot carries all four methods plus a few of its own.

Method	Purpose
`sendMessage(text, opts)`	As above. `opts` also accepts the bare string `'host'`.
`attachData(name, data, contentType?)`	As above.
`setHostBusy(busy, label?)`	As above.
`setContext(object)`	As above. Whole-object replace.
`setSession(session)`	Hands the chat window a session your own server minted. Only does anything with `data-session="host"`. See below.
`onAction(fn)`	Subscribes to agent actions. See Receiving Agent Actions.
`open()` / `close()` / `toggle()`	Opens and closes the bubble panel.
`reset()`	Forgets the conversation and starts a fresh one in place.
`terms()`	Opens the Terms overlay the footer links to.
`debug()`	Reports the frame address, the configuration read off the tag, and the current conversation ID.

Everything the chatbot posts is also relayed onto your page as a flourish: event on window, so you can listen without writing a postMessage handler. The name is the message name without its fl__ prefix.

window.addEventListener('flourish:sessionready', function (e) { /* e.detail */ });
window.addEventListener('flourish:action', function (e) { e.detail.payload; });

Events the loader has never heard of are relayed too, so a new one reaches your listeners without you changing anything.

Origin security. The chatbot only accepts messages from the parent origin it derives from document.referrer. If your host strips the referrer (Referrer-Policy), pass the parent origin explicitly by adding a c__flparentorigin parameter to the Site URL (e.g. c__flparentorigin=https://your-app.example.com). If no origin can be determined, all inbound messages are rejected.

Example: using the hosted loader's wrapper

<script src="https://cdn.toflourish.org/agent-platform/v1/chatbot-embed.js" defer
  data-agent-id="49b3512c-…" data-embed-url="https://flourish.my.site.com/agent"
  data-mode="inline"></script>
<script>
  // FlourishChatbot is defined by the loader once the iframe mounts.
  window.addEventListener('message', function (e) {
    // (Optionally verify e.origin against your Site origin here.)
    var msg; try { msg = JSON.parse(e.data); } catch (_) { return; }
    if (!msg || msg.action !== 'fl__sessionready') return;

    // Session is live, so it is now safe to drive the agent.
    FlourishChatbot.setHostBusy(true, 'Searching…');
    var results = /* run your local search */;
    FlourishChatbot.attachData('results.json', results, 'application/json');
    FlourishChatbot.sendMessage(
      'Attached results.json (' + results.length + ' hits). Answer the pending question from it, citing sources.'
    );
    FlourishChatbot.setHostBusy(false);
  });
</script>

Example: hand-rolled iframe (raw postMessage)

<iframe id="fl-chatbot"
  src="https://flourish.my.site.com/agent?c__flagentid=49b3512c-…&c__flparentorigin=https://your-app.example.com"
  allow="clipboard-write"></iframe>
<script>
  var iframe = document.getElementById('fl-chatbot');
  var CHATBOT_ORIGIN = 'https://flourish.my.site.com'; // the Site origin
  function post(payload) {
    iframe.contentWindow.postMessage(JSON.stringify(payload), CHATBOT_ORIGIN);
  }
  window.addEventListener('message', function (e) {
    if (e.origin !== CHATBOT_ORIGIN) return;
    var msg; try { msg = JSON.parse(e.data); } catch (_) { return; }
    if (msg && msg.action === 'fl__sessionready') {
      post({ action: 'fl__setHostBusy', busy: true, label: 'Searching…' });
      post({ action: 'fl__attachData', name: 'results.json', data: myResults, contentType: 'application/json' });
      post({ action: 'fl__sendMessage', text: 'Attached results.json. Answer from it.', origin: 'host' });
      post({ action: 'fl__setHostBusy', busy: false });
    }
  });
</script>

Note on host-origin messages. origin: 'host' messages are delivered to the agent tagged as host notifications rather than user turns, and are hidden from the visible transcript (live and on history reload). Whether a host-origin message elicits a response is decided by the platform. If a message doesn't produce a reply, that is the expected behavior for a notification.

Minting the session yourself

Most embeds do not need this. The chat window opens its own connection when it loads, and that is the right answer whenever the agent and the data belong to the same organization. Read this only if the agent has to run against data belonging to whoever is visiting, rather than to whoever owns the agent.

The credential that says whose data a conversation runs on cannot go in a web page. So the exchange happens on a server, and the browser carries only the short-lived token that comes back.

Set data-session="host" on the script tag. That tells the chat window not to open a connection of its own, and it will wait to be handed one.

<script src="https://cdn.toflourish.org/agent-platform/v1/chatbot-embed.js" defer
  data-embed-url="https://flourish.my.site.com/agent"
  data-agent-id="49b3512c-..."
  data-session="host"></script>

Your server mints the session exactly as a web app's session endpoint does, and your page hands the result in:

FlourishChatbot.setSession({
  conversationId: '79a1df5e-13ff-4b81-aff3-a4f04a8324bf',
  token: 'eyJhbGciOi...',
  wsUrl: 'wss://...',
  agentName: 'Support',
  chatbotTitle: 'Ask us anything'
});

conversationId and wsUrl are the two that matter: a session missing either is ignored. The rest are cosmetic, filling in the agent's name and the panel title before the first message arrives, and the chat falls back to what it already knows without them.

Four things to know:

setSession does not wait for fl__sessionready, unlike every other method on the wrapper. It cannot: the session is what makes the window ready, so holding it back would leave the chat waiting on itself forever. Call it whenever your server answers.
Call it as early as you like. In bubble mode the frame is not built until the panel first opens, and a session minted before that is held and delivered when the frame appears. The chat window also asks for one as soon as it can listen, so neither side has to guess about the other.
You have 20 seconds. If nothing arrives, the chat stops waiting and says so on the page: This page was expected to supply a chat session and did not. Check that it minted one and called setSession. That message is the one to look for when an embed sits on its loading state, and it means your endpoint, not the agent.
Without data-session="host" it does nothing, and the chat window opens its own connection as usual. That is also what happens if the window's own build predates the attribute, so an older org gets the previous behavior rather than a broken chat.

Receiving Agent Actions in the iframe

The reverse of fl__sendMessage: when the agent invokes a Custom Action, whether delivered as a structured action or a legacy :::action ... ::: text block, the chatbot posts it to the parent as an fl__action message. This is the cross-frame equivalent of the agentaction DOM event that a same-document LWC parent receives (see Handling Agent Actions). Both fire, so the action reaches whichever kind of host is embedding.

The message shape is { action: 'fl__action', payload: { type, ...params } }, where type is the action's action_type and the rest are its validated parameters, e.g. { type: 'query_corpus', query: 'venmo transfer', perPage: 15 }.

Receiving it (hosted loader):

// FlourishChatbot is defined by chatbot-embed.js.
const off = FlourishChatbot.onAction(function (action) {
  // action = { type, ...params }
  if (action.type === 'query_corpus') runSearch(action.query, action.perPage);
});
// off() to unsubscribe.

Receiving it (hand-rolled iframe):

window.addEventListener('message', function (e) {
  if (e.origin !== CHATBOT_ORIGIN) return;              // your Site origin
  var msg; try { msg = JSON.parse(e.data); } catch (_) { return; }
  if ((msg.type || msg.action) === 'fl__action') {
    handleAction(msg.payload);                            // payload = { type, ...params }
  }
});

fl__action is posted only to the validated parent origin (the one derived from document.referrer or the c__flparentorigin param), never *. Custom actions with no return value (navigate, filter, bookmark) are one-way UI drivers. To feed results back to the agent, run the work in the host and return via fl__attachData plus fl__sendMessage.

Selecting the Agent at Runtime

To serve a different agent per page, read the ID at runtime and inject the loader tag yourself instead of pasting a static snippet.

<script>
  var agentId = new URL(location.href).searchParams.get('agent') || 'DEFAULT_AGENT_ID';
  var s = document.createElement('script');
  s.src = 'https://cdn.toflourish.org/agent-platform/v1/chatbot-embed.js';
  s.defer = true;
  s.dataset.agentId = agentId;                 // the loader turns this into c__flagentid
  s.dataset.embedUrl = 'https://yourorg.my.site.com/chatbot';
  document.body.appendChild(s);
</script>

Overview​

Adding the Chatbot to a Salesforce Page​

Properties​

Passing Context​

Custom Styling​

Colors​

Show / Hide Components​

Layout​

Text and language​

Dark Mode​

Streaming Responses​

Stopping a reply​

Adding to a request while it is working​

Progress Notifications​

File Uploads​

How It Works​

Pasting​

File Downloads​

Markdown Rendering​

Conversation History​

Utility Bar​

Connection & Reconnection​

Embedding on External Websites​

Prerequisites​

Generating the Snippet​

Where to Paste the Snippet​

Snippet attributes​

Passing the Agent ID​

Test Mode​

Bubble Mode Behavior​

Inline Mode Behavior​

Keeping the Conversation Across Pages​

Customizing the Embed​

For Developers​

Basic Markup​

Property Reference​

Setting Context Programmatically​

Host API Methods​

Handling Agent Actions​

Custom Style Markup​

Embedding Examples​

Iframe Integration​

postMessage Events​

Driving the Chatbot from the Parent Page (Host API)​

Minting the session yourself​

Receiving Agent Actions in the iframe​

Selecting the Agent at Runtime​