floe
Home / Docs / Support Agent

Support Agent

Floe can answer a product question with steps from your site's content. When the user asks to see or carry out a supported workflow, the in-product agent can navigate to the relevant screen and guide the task.

When a question exactly matches one published FAQ reference guide, the agent can give that guide's answer with its stated limits. A request to perform an action still follows the configured workflow and its checks.

How it works

The same in-product agent that handles onboarding also handles support. When a user gets stuck:

  1. They ask the agent by voice, or choose text mode for silent replies
  2. For a how-to question, the agent gives the documented steps and says when a detail needs verification
  3. If the user asks to open a screen or complete a supported workflow, the agent navigates within the authorized site and guides the task
  4. For a supported change, it confirms the intended action, performs it, and checks the result

In voice mode the agent speaks its reply to you rather than the internal planning notes or echoed tool-call text it works from.

The user stays in your product instead of switching to a help center. Available operations depend on the workflows configured for the site. A review or explanation does not itself change a setting. A prepared request is not a submitted request or a connected integration; the agent reports which outcome it actually verified. For a configured portal request review, it reads back the account name and recipient shown on the form. If either value needs correction, the agent enters the corrected value, checks both fields again, and asks for a fresh review. It reports the unsent form as discarded only after confirming it closed without saving. If a change cannot be verified, the agent reports that uncertainty instead of treating an attempted action as success.

A finished review or explanation is reported as complete and the agent continues without waiting for you to acknowledge it. It still asks when a detail it needs has not been supplied, or when it needs your approval before a change.

In a supported form review, you can correct the displayed value directly in the field. With a compatible browser integration, Floe checks the corrected form and asks you to review it again. Typing a correction does not approve Save or Keep; wait for the new review before choosing. For an incomplete or invalid field, Floe asks you to enter a valid value and leave the field to check again. You can also stop the walkthrough; the previous approval will not be used to act on an unverified correction.

For a configured submission that requires approval, Floe checks the specified page settings, reads back what it verified, and waits for your next explicit choice before submitting. It identifies settings it could not verify; the readback alone does not submit a request. Some unclear transcriptions of “queue this export” trigger a fresh choice request; repeating that ambiguity stops the workflow without submitting. Declining an action does not approve it, even when your reply repeats the action name, such as “Don’t actually queue this export.” At a reviewed import-mapping choice, “Do not confirm the mapping or schedule the upload” cancels that choice; asking to keep reviewing does not grant approval.

For a staff-configured file-selection workflow, the agent can ask you to choose a file in your browser and supply that file to a specific upload control in your product. The prompt names the destination site. Use Choose file, review the selected filename and size shown in Floe's prompt, then select Supply this file. Floe assigns the file to the site's upload control only after that confirmation; the page hosting Floe may access a selected file before you confirm. You can select Cancel file selection before Floe supplies the file. Floe checks the configured filename extension and byte count before supplying it; this does not inspect file contents to establish the type. Supplying a file does not tell Floe to click a separate Import or Confirm button; any later import step needs its own reviewed workflow and approval. Availability depends on Floe enabling and validating that workflow for your site. If the upload control cannot be found before file supply, the agent reports the step as incomplete. If Floe attempts to supply the file but cannot verify its result, it stops and reports that the selection may have reached the form. Check the upload form, and any upload or import status your product shows, before trying again. If a file selection and a later change both remain unconfirmed, Floe reports both outcomes as uncertain and asks you to check the affected form, records, or tracker before making further changes.

A validated workflow can also support sites that replace the upload control after accepting a file. Floe checks the selected file and a new acceptance confirmation before continuing. This requires compatible browser support; an older integration stops before file selection and asks you to refresh it. File acceptance or a scheduled import is not reported as a completed import: final processing results need their own verification.

For a staff-configured workflow, an unconfirmed submission may be followed by a read-only check of the current state. Floe does not resend that submission or report it as successful merely because matching data is visible; it explains what remains unconfirmed.

Setup

The support agent is the in-product overlay running in on-demand mode. It uses neither demoMode nor websiteAgent; activation: "on_demand" gives the host-page agent its support posture.

Load the SDK once, then initialize it from a script served by your own application:

<!-- Add these before the closing </body> tag. -->
<script src="https://cdn.floe.so/floe-sdk.iife.js" defer></script>
<script src="/floe-init.js" defer></script>

// floe-init.js — served from your own origin
const floe = Floe({
  clientKey: "YOUR_CLIENT_KEY",
  activation: "on_demand",
  userInfo: {
    externalId: "YOUR_AUTHENTICATED_USER_ID",
    email: "user@example.com",
    name: "Ada Lovelace",
    company: "Analytical Engines",
    designation: "Workspace admin",
  },
  nudge: {
    text: "Need a hand?",
    autoShow: false,
    autoHideDelay: 10000,
  },
  launcher: { position: "bottom-right", inset: 24 },
  enableAudio: true,
  enableScreenCapture: true,
});

floe.ready.catch((error) => {
  console.error("Floe failed to initialize", error);
});

// Keep the instance in your app integration. On logout or teardown:
// await floe.disconnect();

Both in-product variants start as a collapsed launcher and connect a session only after the user clicks. activation: "on_demand" changes how that launcher behaves and how the conversation opens:

  • No nudge bubble by default. The launcher sits quietly. (Set nudge: { autoShow: true } if you do want it to reach out.)
  • No session until the user asks. Nothing is spawned — and nothing is billed — for a user who never opens it.
  • A reactive opening. When they click, the agent asks what they need instead of proposing a setup walkthrough. If they send a question while the session is starting, the agent answers it once ready and skips the opening question.

Everything else is unchanged. Ask it to create a report and it runs the same guided workflow the onboarding agent would; on-demand governs whether the launcher reaches out and how the conversation starts, not what the agent can do once it has started.

Pass userInfo when the agent needs non-secret name, company, role, or account context during this support session. It is unverified browser input, even on a page behind login, so Floe does not treat it as authentication. Call floe.disconnect() on logout or teardown, as in the example above; disconnecting stops the agent but does not undo a value it already entered in your product.

Live account data with MCP

This section is Floe as an MCP client — the Support Agent calling your MCP server. If you are looking for the other direction, connecting your own AI tool to Floe to work with Floe as a product, that is Connect your AI tools to Floe.

Support mode can connect one authenticated, remote Model Context Protocol (MCP) server for the lifetime of a support session. This lets the agent answer account-specific questions such as "What is the current account summary?" without adding that data to userInfo or Floe's knowledge base. Any public HTTPS endpoint works; you do not need to register it with Floe.

If a lookup is unavailable, denied, or incomplete, the answer says so instead of guessing.

const floe = Floe({
  clientKey: "YOUR_CLIENT_KEY",
  activation: "on_demand",
  userInfo: {
    externalId: currentUser.id,
    email: currentUser.email,
  },
  mcp: {
    serverUrl: "https://mcp.example.com/mcp",
    // Ask your authentication client for the freshest user token.
    getBearerToken: () => auth.getAccessToken(),
    // Replace this example with exact, read-only tool names from your server.
    allowedTools: ["get_account_summary"],
  },
});

Provide three values:

  • serverUrl: your public Streamable HTTP endpoint, on HTTPS with the default port and no query string, fragment, or embedded credentials. Redirects are not followed.
  • getBearerToken: a function that returns the current user's short-lived token, synchronously or as a promise, within five seconds. Return the raw token without a Bearer prefix; your server receives it as Authorization: Bearer <token>.
  • allowedTools: 1–20 unique, exact, case-sensitive MCP tool names Floe may call — letters, digits, _, . and -, up to 128 characters. A name outside that set is rejected and the session starts without MCP, with no error surfaced (a warning is logged only with debug: true), so check the names before you ship. The agent calls a tool only when a question needs current account data; general how-to questions are still answered from your content. Expose only read-only tools.

The SDK calls getBearerToken once when the user opens the support launcher and keeps no copy of the token after the session starts. Give the token enough remaining lifetime for the expected conversation. If the callback returns no token, throws, or your server is unavailable, the support session continues without MCP tools. A new support session calls the callback again.

To keep live account data out of retained artifacts, MCP-enabled support sessions are not recorded and produce no stored summary. If you need an audit trail for live-data access, record it at the MCP server under your own authorization and retention policy.

Floe validates serverUrl at session start and refuses private, loopback, or otherwise non-public destinations. Tools whose input schema Floe cannot represent (including objects with more than 50 properties) are skipped; if none of the configured tools are usable, the session continues as ordinary support. Custom authentication headers and transports other than Streamable HTTP are not supported.

Treat the browser token as a user credential:

  • Mint a short-lived, MCP-audience token with only the scopes that user needs. Do not send an admin token or a refresh token.
  • Keep allowedTools narrow and read-only. Your MCP server must still authorize every tool call from the token; this list is an additional exposure control, not an authorization boundary.
  • Keep your existing Content Security Policy and XSS protections in place. Do not embed a long-lived secret in the JavaScript bundle.
  • Do not place the token in userInfo, metadata, the MCP URL, or a query string.

MCP is available only with activation: "on_demand". It is ignored for proactive onboarding, demo mode, and the website agent.

Dashboard configuration

Support shares the Onboarding Agent configuration in the dashboard; there is no separate Support Agent configuration to maintain. Enable and configure the Onboarding Agent for the site, then use activation: "on_demand" in the embed. Support sessions run with voice and text; the video avatar is a Website Agent feature and has no onboarding or support equivalent.

Personality & tone on that configuration applies to support sessions too: tone, identity, and answer length. See Dashboard configuration.

Configuration reference

  • clientKey (string, required): the public browser key from Onboarding Agent → Setup or site settings. It is meant for browser code; never expose the site's secret API key. A client key works from any site until it is restricted to your domains, which Floe does on request: send us each production app origin.
  • activation ("on_demand"): required for the support posture. It is ignored if demoMode or websiteAgent is set.
  • userInfo (object, optional): supplies current-session context. Supported fields are externalId, email, name, company, designation, and metadata. It is unverified browser input, not an authentication assertion. Never put access tokens or other secrets in metadata; MCP authorization belongs only in getBearerToken.
  • mcp (object, support only): { serverUrl, getBearerToken, allowedTools }, as described above.
  • nudge (object): accepts text, autoShow, and autoHideDelay. autoShow defaults to false under on_demand. autoHideDelay is milliseconds; 0 keeps the nudge open. Set both values explicitly when opting into a contextual nudge.
  • launcher (object): { position: "bottom-right" | "bottom-left", inset: number }. It defaults to bottom-right with a 24-pixel inset. Move it when another support widget occupies that corner.
  • enableAudio (boolean, default true): sets the initial microphone preference. Users can keep typing if microphone access is denied or unavailable, and a user's remembered microphone preference can override the initial value.
  • enableScreenCapture (boolean, default true): makes screen sharing and screenshot context available. The browser still requires a user gesture and permission before sharing a screen.
  • debug (boolean, default false): enables verbose SDK logs while diagnosing an integration.
  • apiUrl (string, advanced): overrides the Floe API endpoint. Leave it unset with the production CDN build.

Integrate with a coding agent

Copy this prompt into your coding agent from the root of your application repository:

Integrate Floe's in-product support agent into this application. Find the client-only root that mounts once after authentication resolves. Load https://cdn.floe.so/floe-sdk.iife.js exactly once and initialize it from /floe-init.js (or the framework's equivalent client-only lifecycle). Call Floe() exactly once with the public client key and activation: "on_demand". If current-session personalization is useful, map only non-secret display context into userInfo; do not treat it as an identity or authorization assertion. Do not set demoMode, websiteAgent, or demoSiteId. Keep the launcher quiet unless the product has a deliberate contextual-help route; if you add a nudge, set autoShow and autoHideDelay explicitly. Store the returned instance, handle instance.ready, and call instance.disconnect() on logout or component teardown. Do not call init() yourself or call a destroy() method. Prevent duplicate initialization under React Strict Mode. Keep the client key in a public environment variable, never expose Floe's secret API key, and never put access tokens in userInfo.metadata. Preserve the application's existing authentication and client-side routing behavior.

Running onboarding and support together

They are the same agent on the same surface, differing in whether the launcher reaches out and how the opening is framed. One embed can serve both after your own signup state has resolved:

const activation = user.onboardingCompletedAt ? "on_demand" : "proactive";

const floe = Floe({
  clientKey: "YOUR_CLIENT_KEY",
  activation,
  userInfo: {
    externalId: user.id,
    email: user.email,
    name: user.name,
  },
  nudge: {
    text: "Need a hand?",
    autoShow: activation === "proactive",
    autoHideDelay: 10000,
  },
});

floe.ready.catch((error) => {
  console.error("Floe failed to initialize", error);
});

// Keep the instance in your app integration. On logout or teardown:
// await floe.disconnect();

New accounts get an onboarding nudge and setup-oriented opening after they click. Everyone else gets a quiet help launcher that waits to be asked.

Action, not documentation

Traditional support chatbots search your knowledge base and paste an article. The user reads it, tries to follow the steps, gets confused at step 3, and files a ticket anyway.

The agent uses product knowledge from ingestion to answer how-to questions directly. When the user asks for hands-on help, it can use configured capabilities to guide them in your product.

Deciding when the agent reaches out

You control how forward the agent is, per user, with two settings.

activation decides whether the collapsed launcher reaches out and which opening the agent uses after a click. on_demand (above) keeps it quiet until clicked — the right default for a support surface, where an agent that interrupts is worse than no agent. proactive auto-shows an onboarding nudge and uses a setup-oriented opening for brand-new accounts.

nudge decides whether the collapsed launcher slides out a message while it waits:

const floe = Floe({
  clientKey: "YOUR_CLIENT_KEY",
  activation: "on_demand",
  nudge: {
    text: "Stuck on something? Ask me.",
    autoShow: true,
    autoHideDelay: 10000,
  },
});

floe.ready.catch((error) => {
  console.error("Floe failed to initialize", error);
});

// Keep the instance in your app integration. On logout or teardown:
// await floe.disconnect();

Under on_demand the nudge is off unless you ask for it, as above. Under proactive it is on by default. It is capped at three impressions with a seven-day cooldown after a dismissal, and it stops appearing once the user has engaged, so opting in doesn't turn into pestering.

Scope it: a nudge on a complex setup screen earns its keep in a way that a nudge on every page does not.

Verified support workflows

Support coverage is the set of workflows Floe has configured for your site; contact Floe to enable or extend it. A workflow can explain a setting, walk a user through a change, or make a requested change. An explanation or a review never changes a setting.

Before it starts a workflow, the agent shows the record or setting and the action it will take, and asks for clarification when the intended record, value, option, or screen is unclear. When a configured workflow requires a named target — which file, record or screen — the agent asks for it before it opens or changes anything, and it does not pick one on the user's behalf or treat "whichever you think is right" as a choice. When it offers a choice between an inspection, an explanation, or cancellation, it follows only the option selected in the user's latest request or reply; an explanation or cancellation does not open the page. A request it cannot serve does not start. It verifies the outcome before reporting a change complete, and says plainly what it could not verify. It stops when it cannot safely continue — access is denied, the page does not match the workflow, or a result cannot be checked — and reports the workflow as stopped rather than completed. Stopping prevents further actions, but it does not undo a change your application has already saved.

For a provider request or data export, the agent can ask for missing provider, recipient, account, or export scope details before proceeding. If a selected provider workflow does not match the provider you named, the agent stops it before opening anything and can continue only with a matching available workflow. Where reviewed import or export workflows are available, Floe also checks that a requested file-picker import or queued export matches the selected workflow before opening it. A statement that it did not open a dialog or submit a request describes only the current request; it does not establish whether an earlier request succeeded or whether a file was produced.

Some record-change workflows require an exact name and full phone number. Provide those identifiers before starting that change; an alternative identifier is usable only when that workflow supports it.

For workflows configured with an unsaved draft and a separate Save approval, cancelling the reviewed draft closes it and ends the workflow as stopped once that cancellation is verified. The closing reply reports the verified cancellation and any remaining steps. It does not report the requested change as completed. Cancellation does not undo changes saved earlier in the session.

Reviewing support sessions

Open Onboarding Agent → Recordings to review the sessions shared by onboarding and support. Each recording can include the session context supplied by your embed, start time, duration, voice-or-text mode, transcript, captured frames, and the on-page actions the agent took, when that data is available. Browser-supplied userInfo is shown as context, not verified identity. Recordings require conversation access, which owners and admins have.

Floe only acts through the browser workflows, and through API execution if Floe has enabled it for your site at your request. Keep your existing human-support path available for billing changes, refunds, or other work outside that scope; the SDK does not create a support ticket automatically.

FAQ

Does the support agent replace my support team? No. It handles the repetitive "how do I do X" questions to reduce customer effort score so your team can focus on complex issues that need a human.

Can the agent handle billing or account questions? It can navigate to billing screens and explain what the user sees. It can make changes that require API access only when Floe has enabled API execution for your site at your request; otherwise, keep your existing human-support path available.

How does it know the answer? From your ingested content. The more thorough your docs and knowledge base, the better the agent handles support questions.