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.

import { FirstflowProvider } from "@firstflow/react";
Wrap your app root with FirstflowProvider. Mount it once, above any component that renders FirstflowWidget or calls Firstflow hooks. Do not nest providers.

​
Usage

<FirstflowProvider
  agentId={import.meta.env.VITE_FIRSTFLOW_AGENT_ID}
  apiKey={import.meta.env.VITE_FIRSTFLOW_API_KEY}
  user={{
    id: currentUser.id,
    email: currentUser.email,
    traits: {
      plan: currentUser.plan,
      role: currentUser.role,
    },
  }}
  onError={(err) => console.error("[Firstflow]", err)}
>
  {children}
</FirstflowProvider>

​
Props

​
agentId
string
required
Your agent ID from the Dashboard. Identifies which agent’s experiences to load.
​
apiKey
string
required
Your public API key from the Dashboard. Used to authenticate SDK requests.
​
user
UserContext | null
Current user context. Required for any experience that uses audience targeting, segments, or decision conditions that reference traits.*.
interface UserContext {
  id: string;
  email?: string;
  name?: string;
  traits?: Record<string, unknown>;
}
Pass null to clear the user (e.g., after logout). You can also update the user at any time by calling firstflow.setUser().
​
initialSdkPayload
object
Pre-fetched SDK config from getFirstflowConfig() (Next.js only). When provided, the client hydrates immediately without a network request. See the Next.js quickstart.
​
fallback
ReactNode
Rendered while the initial config is loading. Defaults to rendering children immediately (no fallback). Use this if you need to block rendering until config is available.
​
onError
(error: Error) => void
Called if the config fetch fails. The SDK silently no-ops if this prop is not provided — experiences simply don’t render.
​
onExperienceUserPrompt
(event: ExperienceUserPromptEvent) => void
Called when a flow node triggers a user message prompt — for example, when a button CTA has a configured prompt value. Use this to inject the prompt text into your chat input.
interface ExperienceUserPromptEvent {
  experienceId: string;
  nodeId: string;
  prompt: string;
}
Example:
<FirstflowProvider
  onExperienceUserPrompt={({ prompt }) => {
    setChatInput(prompt); // inject into your composer
  }}
>

​
Notes

  • Config is cached in memory for 5 minutes per agentId + apiKey pair
  • Multiple providers with the same credentials share the cache
  • Call firstflow.refreshConfig() to bypass the cache and force a fresh fetch