Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstflow.app/llms.txt

Use this file to discover all available pages before exploring further.

​
FirstflowProvider props

​
agentId
string
required
Agent ID from the Dashboard.
​
apiKey
string
required
Public API key from the Dashboard (agent settings → API Keys).
​
user
UserContext | null
Current user. Pass null when logged out.
interface UserContext {
  id: string;
  email?: string;
  name?: string;
  traits?: Record<string, unknown>;
}
Traits are used for audience targeting. Example:
{
  id: "user_123",
  email: "alice@example.com",
  traits: {
    plan: "pro",
    role: "admin",
    company_size: 200,
  },
}
​
initialSdkPayload
object
Pre-fetched config from getFirstflowConfig() (Next.js only). Bypasses the client-side fetch.
​
fallback
ReactNode
Rendered while config loads. Defaults to rendering children immediately.
​
onError
(error: Error) => void
Called if the config fetch fails. The SDK silently continues without experiences if not provided.
​
onExperienceUserPrompt
(event: ExperienceUserPromptEvent) => void
Called when an experience flow node fires a user-facing prompt (e.g., a button with a configured ctaPrompt). Wire this to your chat input to inject the message:
<FirstflowProvider
  onExperienceUserPrompt={(event) => {
    sendMessage(event.prompt);
  }}
>

​
FirstflowWidget props

​
experiencePlacement
"overlay" | "inlineStack"
default:"\"overlay\""
  • overlay — centered modal over the chat
  • inlineStack — inline, above the composer
​
experienceMinimize
boolean
default:"false"
Show a minimize button. Users can collapse the experience and restore it later.
​
appearance
"light" | "dark" | "auto"
default:"\"auto\""
Color scheme. auto follows the OS preference.
​
onShow
(experienceId: string, type: string) => void
Fires when an experience becomes visible.
​
onDismiss
() => void
Fires when an experience is dismissed.

​
Experience settings

All experience settings are configured in the Dashboard. The following documents every field.

​
Triggers

When an experience shows. Multiple triggers can be configured — an experience fires when any one of them matches.
show_on valueWhen it fires
chat_opensWhen the user’s chat session starts
after_user_messageAfter the user sends their first message
after_idleAfter the user has been idle for delay_seconds
custom_eventWhen your code calls firstflow.analytics.track("your-event-name")
Each trigger can have optional conditions. Conditions refine who the trigger fires for (e.g., “after_user_message AND plan equals pro”). Conditions use the same operators as audience rules.

​
Audience

Who sees the experience.
TypeBehavior
allShow to every user
segmentShow only to members of a named segment
rulesShow when user traits match a set of rules (AND or OR)
Segment membership is computed server-side and returned in the SDK config. Trait rules are evaluated client-side against user.traits.

​
Audience rule operators

OperatorDescription
equalsExact match
not_equalsNot equal
containsString contains substring
not_containsString does not contain
inValue is in list
not_inValue is not in list
gt / gteGreater than / greater than or equal (numeric)
lt / lteLess than / less than or equal (numeric)
existsField is not null
not_existsField is null
Trait paths support dot notation: traits.plan, traits.company.size. Direct user fields (id, email) are also resolvable.

​
Device

ValueMatches
allAny device
desktopNon-mobile user agents
mobileMobile user agents (Android, iPhone, iPad)
Device detection uses navigator.userAgent.

​
Schedule

SettingOptions
Startnow or a specific date/time with timezone
Expirationnone or a specific date/time with timezone

​
Frequency

How many times an experience can show to the same user.
TypeBehavior
onceOne time, forever
limitedUp to N times per session, day, week, or lifetime
alwaysNo limit
Frequency is tracked in localStorage (or sessionStorage for session-scoped limits) using keys prefixed with ff_exp_. Clear these keys to reset frequency during testing: 
Object.keys(localStorage)
  .filter((k) => k.startsWith("ff_exp_"))
  .forEach((k) => localStorage.removeItem(k));

​
Priority

Integer. Higher values are shown first when multiple experiences are eligible simultaneously. Default is 0.

​
Placement

Per-experience override for FirstflowWidget’s default placement. Can be set on individual nodes too.

​
Theming

Widget colors and radii are configured in the Dashboard (agent → Settings → Widget UI). The SDK injects CSS custom properties automatically.

​
CSS custom properties

/* Light mode */
--ff-surface-color: #ffffff;
--ff-surface-muted: #f5f5f5;
--ff-border-color: #e5e5e5;
--ff-text-color: #171717;
--ff-text-muted: #737373;
--ff-accent-color: #0d9373;
--ff-accent-contrast: #ffffff;

/* Dark mode */
--ff-surface-color: #0a0a0a;
--ff-surface-muted: #171717;
--ff-border-color: #262626;
--ff-text-color: #fafafa;
--ff-text-muted: #a3a3a3;
--ff-accent-color: #10b981;

​
Theme object (dashboard config)

type FirstflowWidgetUi = {
  primaryColor?: string;
  primaryContrastColor?: string;
  light?: ThemeMode;
  dark?: ThemeMode;
  radii?: {
    shellRadius?: string;
    controlRadius?: string;
    containerRadius?: string;
  };
};

​
SDK settings

Agent-level settings returned with config:
SettingDefaultDescription
poweredByFirstflowtrueShow “Powered by Firstflow” branding in the widget chrome

​
Config refresh

const firstflow = useFirstflow();

// Force reload config (e.g., after publishing a change in the Dashboard)
await firstflow.refreshConfig();
Config is cached in memory for 5 minutes. refreshConfig() bypasses the cache.

​
Programmatic reset

// Clear user, memberships, frequency records, and config cache
firstflow.reset();
Use after logout to ensure a fresh state for the next user.