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.

​
Install

npm install @firstflow/react

​
Add environment variables

# .env
VITE_FIRSTFLOW_AGENT_ID=your-agent-id
VITE_FIRSTFLOW_API_KEY=your-api-key
Get your agent ID and API key from the Dashboard under Settings → API keys.

​
Add the provider

Wrap your app root with FirstflowProvider. Place it above any component that needs to access the SDK. 
import { FirstflowProvider } from "@firstflow/react";

export default function App() {
  return (
    <FirstflowProvider
      agentId={import.meta.env.VITE_FIRSTFLOW_AGENT_ID}
      apiKey={import.meta.env.VITE_FIRSTFLOW_API_KEY}
      user={{
        id: currentUser.id,
        traits: {
          plan: currentUser.plan,
          role: currentUser.role,
        },
      }}
    >
      <ChatApp />
    </FirstflowProvider>
  );
}

​
Wrap your chat UI

Wrap the component that contains your message list and composer with FirstflowWidget. Experiences render relative to this boundary. 
import { FirstflowWidget } from "@firstflow/react";

export function ChatApp() {
  return (
    <FirstflowWidget experiencePlacement="inlineStack">
      <MessageList />
      <Composer />
    </FirstflowWidget>
  );
}

​
Create and publish an experience

  1. Go to the Dashboard and open your agent
  2. Click Experiences → New experience
  3. Build a tour or survey in the flow editor
  4. Set Status to Active and click Publish
The SDK fetches config every 5 minutes. To force an immediate reload, call firstflow.refreshConfig().

​
Next steps

FirstflowProvider

All provider props and configuration options

FirstflowWidget

Widget props and placement options

useFirstflow()

Instance methods: setUser, track, reset

Survey

Render surveys outside the widget