# FirstFlow

## Docs

- [Introduction](https://docs.firstflow.app/introduction.md): FirstFlow is an open-source SDK for onboarding, tours, surveys, and LLM observability in AI agent and chat products running entirely on your own infrastructure.
- [How it works](https://docs.firstflow.app/how-it-works.md): The FirstFlow architecture: why the backend decides everything, how a finished widget reaches the browser over Socket.IO, and what the two SDKs actually do.
- [Quickstart](https://docs.firstflow.app/quickstart.md): Install both SDKs, link the browser and server with one shared conversation id, and ship your first server-pushed experience.
- [Core concepts](https://docs.firstflow.app/concepts.md): One model spans the dashboard, the backend, and the SDKs: agents hold experiences, the server decides what to show, and a widget is pushed to the browser.
- [Features](https://docs.firstflow.app/features.md): Every FirstFlow capability in-chat experiences, server-side targeting, conversation analytics, two SDKs, and an MCP server and how they fit together.
- [In-chat experiences](https://docs.firstflow.app/features/experiences.md): The four experience types FirstFlow delivers inside the conversation guides, tours, surveys, and announcements and how the server composes and pushes them.
- [Authoring](https://docs.firstflow.app/features/authoring.md): Build experiences as flow graphs by hand, by AI, or imported from a URL then add branching, side-effects, and theming.
- [Analytics & sessions](https://docs.firstflow.app/features/analytics.md): Turn observed conversations into volume and cost metrics, full session transcripts, LLM-graded quality scores, and topic/intent/sentiment classification.
- [Targeting](https://docs.firstflow.app/features/targeting.md): How FirstFlow decides who sees an experience and when triggers, audience, schedule, frequency, and the LLM classifier, all evaluated server-side.
- [Developer platform](https://docs.firstflow.app/features/platform.md): The two SDKs, realtime widget, MCP server, and widget-kit that integrate FirstFlow into an AI agent product.
- [Integrations](https://docs.firstflow.app/features/integrations.md): How FirstFlow connects to the outside world Slack, your webhooks and APIs from inside a flow, and the LLM providers that power its AI features.
- [Agents](https://docs.firstflow.app/concepts/agents.md): The workspace container that scopes experiences, audience, conversations, keys, and settings and the identity the SDKs route through.
- [Experiences](https://docs.firstflow.app/concepts/experiences.md): The deliverable unit in FirstFlow a typed, flow-driven guide, tour, survey, or announcement that the server evaluates and pushes into chat.
- [Flows & nodes](https://docs.firstflow.app/concepts/flows-and-nodes.md): How a flow graph defines an experience, how the backend walks it at runtime, and what each node type does.
- [Triggers & audience](https://docs.firstflow.app/concepts/triggers-and-audience.md): How FirstFlow decides when an experience fires and who is eligible the trigger, condition, audience, schedule, and frequency gates the backend evaluates server-side before pushing a widget.
- [Audience & segments](https://docs.firstflow.app/concepts/audience.md): The end-user directory FirstFlow builds from your identity calls, and the precomputed segments that gate which experiences each user sees.
- [Conversations & sessions](https://docs.firstflow.app/concepts/conversations-and-sessions.md): The host-owned id that joins the widget, the transcript, traces, cost, and any flow run into one thread.
- [Widgets & blocks](https://docs.firstflow.app/concepts/widgets-and-blocks.md): How FirstFlow represents in-chat UI as a declarative WidgetTree of block primitives, how it gets composed and pushed, and how blocks bind, render, and fire actions.
- [AI Connect (MCP) overview](https://docs.firstflow.app/mcp/overview.md): How FirstFlow's MCP server lets a coding agent read your product context and build experiences the OAuth handshake, scope resolution, and per-request tool surface.
- [Connect an agent](https://docs.firstflow.app/mcp/quickstart.md): Point an MCP coding agent at FirstFlow's /mcp endpoint and complete the OAuth + PKCE consent flow so it can build and manage experiences as tools.
- [Tool catalog](https://docs.firstflow.app/mcp/tools.md): Every tool the FirstFlow MCP server exposes what each one does, the scope it requires, and how a coding agent calls it over the OAuth-authenticated /mcp endpoint.
- [Scopes & roles](https://docs.firstflow.app/mcp/scopes.md): How the MCP server derives a caller's scopes from their organization role, gates each tool against those scopes, and what a 403 or a missing tool actually means.
- [API keys](https://docs.firstflow.app/mcp/api-keys.md): Why MCP clients use OAuth instead of static API keys, where each credential is valid, and how the /mcp endpoint enforces the split.
- [Slack](https://docs.firstflow.app/integrations/slack.md): Post a channel message or DM from a flow's slack_message node OAuth-connected, server-side, and fail-open.
- [Webhooks](https://docs.firstflow.app/integrations/webhooks.md): How FirstFlow delivers flow events to your own HTTP endpoints signed, queued through an outbox, and retried with exponential backoff.
- [API calls](https://docs.firstflow.app/integrations/api-calls.md): Fetch live data from an external HTTP endpoint mid-flow, server-side, and reference the response in downstream nodes.
- [AI Providers](https://docs.firstflow.app/integrations/ai-providers.md): How FirstFlow resolves the LLM credentials that power widget composition, classification, and flow generation per-organization keys, Cloudflare Gateway routing, and environment fallback.
- [Troubleshooting](https://docs.firstflow.app/troubleshooting.md): Diagnose widget, server SDK, identity, and self-hosting issues by reasoning from where FirstFlow evaluates each decision.
- [FAQ](https://docs.firstflow.app/faq.md): Direct answers to the questions that come up while integrating FirstFlow keys, the conversation id, who decides what to show, supported providers, and self-hosting.
- [Use these docs with AI](https://docs.firstflow.app/use-docs-with-ai.md): How these docs are built for machine retrieval, and the two ways a coding agent consumes them as context, and as an operator through the MCP server.
- [Browser SDK overview](https://docs.firstflow.app/react/overview.md): @firstflow/runtime is a React widget that loads your experiences, evaluates triggers and audience in the browser, renders the active step, and persists progress to your Supabase.
- [FirstflowProvider](https://docs.firstflow.app/react/provider.md): The provider loads your experiences, runs the trigger engine, identifies the user, and holds runtime state. Mount it once above your app.
- [FirstflowWidget](https://docs.firstflow.app/react/widget.md): The default widget shell renders the active step's blocks, can anchor above a chat composer, and supports minimize.
- [useFirstflow](https://docs.firstflow.app/react/use-firstflow.md): The hook exposes runtime state and the imperative API: start, advance, dismiss, emit events, run actions, and minimize.
- [Identity & traits](https://docs.firstflow.app/react/identity.md): Pass an authenticated user id and traits, or let the runtime use a stable anonymous id for visitors who haven't signed in.
- [Events](https://docs.firstflow.app/react/analytics.md): The runtime emits an event for every meaningful moment. Subscribe with onEvent and route them to your own analytics.
- [Theming](https://docs.firstflow.app/react/theming.md): Re-theme the widget with CSS custom properties, override class hooks for finer control, or build your own shell.
- [Next.js](https://docs.firstflow.app/react/nextjs.md): Use @firstflow/runtime in a Next.js app: mount the provider in a client component and keep the service-role key on the server.
- [Server SDK overview](https://docs.firstflow.app/server/overview.md): @firstflow/runtime-server wraps your LLM client to record tokens, cost, latency, and conversations to your Supabase and classifies intent. No FirstFlow service involved.
- [Wrap your LLM client](https://docs.firstflow.app/server/wrap-llm-client.md): ff.wrap() proxies your OpenAI or Anthropic client so every call records to Supabase. Tag calls with userId and a conversation id; bring your own OpenAI-compatible endpoint.
- [What gets recorded](https://docs.firstflow.app/server/observe.md): The four Supabase tables the server SDK writes to, and the columns on each so you know exactly where your observability data lives.
- [Traces & spans](https://docs.firstflow.app/server/traces.md): ff.withTrace() groups several LLM calls into one trace so a multi-step operation appears as a single row with its calls attached.
- [Conversations & signals](https://docs.firstflow.app/server/outcomes.md): Attach intent, outcome, tags, and notes to a conversation with ff.signal() and ff.tagConversation() set by your own logic, not an LLM.
- [Intent & sentiment](https://docs.firstflow.app/server/analytics.md): Classify a conversation's intent with an LLM (with hysteresis), or score sentiment lexically with no LLM call.
- [Configuration](https://docs.firstflow.app/server/configuration.md): How to construct Firstflow: persistence, content capture, default metadata, the keys it needs, and signed identity tokens.
- [Blocks & custom shells](https://docs.firstflow.app/widget-kit/overview.md): Render experiences with your own UI by combining BlockRenderer with useFirstflow, and understand the block and action model behind each step.
- [Self-hosting overview](https://docs.firstflow.app/self-hosting/overview.md): FirstFlow is an open-source SDK that runs entirely on your own infrastructure: your app, your Supabase project, and your experiences in git. There is no FirstFlow server to operate.
- [Quickstart](https://docs.firstflow.app/self-hosting/quickstart.md): Install the FirstFlow SDK, point it at your own Supabase project, and render your first experience no server to deploy.
- [Set up with an AI agent](https://docs.firstflow.app/self-hosting/ai-setup.md): Copy one prompt into Claude Code, Cursor, or any coding agent and have it wire FirstFlow into your app end-to-end.
- [Set up Supabase](https://docs.firstflow.app/self-hosting/supabase-cloud.md): Create the Supabase project FirstFlow writes to, apply the migrations in order, and collect the keys your app needs.
- [Configuration](https://docs.firstflow.app/self-hosting/configuration.md): Every environment variable FirstFlow reads Supabase keys and an optional AI provider. There is no backend to configure.
- [Identity & auth](https://docs.firstflow.app/self-hosting/auth-and-orgs.md): FirstFlow has no auth system of its own. You bring your own auth, pass a user id, and unidentified visitors get a stable anonymous id.
- [Row Level Security](https://docs.firstflow.app/self-hosting/oauth-providers.md): How FirstFlow's Supabase tables are protected: the anon key writes under RLS from the browser, the service-role key bypasses it on the server, and how to tighten policies around your user ids.
- [What you own](https://docs.firstflow.app/self-hosting/responsibilities.md): Running FirstFlow as an SDK is light on operations. Here is the short list of what stays your responsibility.
- [Production checklist](https://docs.firstflow.app/self-hosting/production.md): What to verify before shipping FirstFlow to production: RLS, key hygiene, migrations, backups, and a quick smoke test.
- [Contributing](https://docs.firstflow.app/self-hosting/contributing.md): Clone the firstflow-oss monorepo, then build and test the packages.

## OpenAPI Specs

- [openapi](https://docs.firstflow.app/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.